@poodle64/librarian 2026.9.21 → 2026.9.23

package/dist/chat.svelte.js

@@ -0,0 +1,554 @@
+/**
+ * The page's controller: one conversation with one agent, over a room's routes
+ * or a job's watch, message and stop.
+ *
+ * A room is asked. Each question streams its own turn, the agent names the
+ * conversation on its `init` event, and the conversation is read back whole
+ * when it is reopened. The turn belongs to the server, not the page: a
+ * refresh, a locked phone or a closed tab leaves it running, so a reopened
+ * conversation whose answer is still being written shows that, with its
+ * clock, and is read again once it settles. Stop is a request to the server
+ * for the same reason, never just a closed connection.
+ *
+ * A job is watched. Somebody else started it; the reader follows it from its
+ * first event, says things to it while it works, and stops it. Its stream is
+ * folded by `Session`, and a stream that closes is opened again when the
+ * reader sends a message, or while the host says the job may carry on.
+ *
+ * Nothing here knows a URL. The transport is the host's own client over the
+ * routes, and its shapes are the routes' own bodies, so a stamped app passes
+ * what its client returns straight through.
+ */
+import { untrack } from 'svelte';
+import { isQueued } from './client';
+import { Session } from './session.svelte';
+import { fold, foldState } from './transcript.svelte';
+/** The events of a run: the agent has the question. */
+const RUN = new Set(['stream_event', 'assistant', 'user', 'result']);
+let minted = 0;
+export class Chat {
+    /** The words in the box and the files with them: bind the composer here,
+     *  so a question the server refuses comes back exactly as typed. */
+    draft = $state('');
+    files = $state([]);
+    /** When an answer this page is not streaming began, epoch ms: a
+     *  conversation reopened mid-answer. */
+    answering = $state(null);
+    /** The agent is answering somebody else's question first. */
+    waiting = $state(false);
+    /** Today's allowance; null until read, and in a job. */
+    quota = $state(null);
+    /** The open conversation, or the job; null for a new one. The host keeps
+     *  it in the address. */
+    conversationId = $state(null);
+    /** This person's conversations, as `list()` last read them; null until then. */
+    conversations = $state(null);
+    listFailed = $state(false);
+    #room = null;
+    #job = null;
+    #pollMs;
+    #rewatchMs;
+    #turns = $state([]);
+    #version = $state(0);
+    #running = $state(false);
+    #session = $state(null);
+    #watching = $state(false);
+    /** Which conversation the page shows, advanced whenever it leaves one: a
+     *  stream still arriving for the one it left must not write into this one. */
+    #generation = 0;
+    #stream = null;
+    #poll;
+    #watch = null;
+    #woken = false;
+    #wake = null;
+    // Plain, as `Session`'s seen-set: nothing renders it.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #held = new Set();
+    constructor(transport, options = {}) {
+        if ('watch' in transport)
+            this.#job = transport;
+        else
+            this.#room = transport;
+        this.#pollMs = options.pollMs ?? 5000;
+        this.#rewatchMs = options.rewatchMs ?? 2000;
+    }
+    /** Every turn, in order. A live one grows in place; key on `version`. */
+    get turns() {
+        return this.#session?.turns ?? this.#turns;
+    }
+    /** Bumped on every event folded, for `Conversation`'s follow-scroll. */
+    get version() {
+        return this.#version + (this.#session?.version ?? 0);
+    }
+    /** This page is streaming an answer. */
+    get running() {
+        if (this.#job)
+            return this.#watching && (this.#session?.working ?? false);
+        return this.#running;
+    }
+    /** Something is being answered, here or out of sight: the composer waits
+     *  and offers Stop. */
+    get busy() {
+        return this.running || this.answering !== null;
+    }
+    /** A job reads what the reader says while it works; a room waits for its answer. */
+    get sendWhileRunning() {
+        return this.#job !== null;
+    }
+    /** Reopen a conversation, or start watching a job. False when it could not
+     *  be read, which leaves the page on a new conversation.
+     *
+     *  Safe to call from an effect that follows the page's address: nothing
+     *  it reads of its own becomes that effect's to follow. */
+    open(id) {
+        return untrack(() => this.#open(id));
+    }
+    async #open(id) {
+        this.#leave();
+        this.conversationId = id;
+        if (this.#job) {
+            this.#follow(id);
+            return true;
+        }
+        this.#turns = [];
+        this.#held.clear();
+        void this.refreshQuota();
+        const mine = this.#generation;
+        try {
+            const read = await this.#room.read(id);
+            if (mine === this.#generation)
+                this.#show(read, mine);
+            return mine === this.#generation;
+        }
+        catch {
+            if (mine === this.#generation)
+                this.conversationId = null;
+            return false;
+        }
+    }
+    /** Back to a new conversation. A turn still being answered goes on without
+     *  the page, and is there when its conversation is reopened. Safe to call
+     *  from an effect, as `open` is. */
+    new() {
+        untrack(() => {
+            this.#leave();
+            this.conversationId = null;
+            this.#turns = [];
+            this.#held.clear();
+            this.#session = null;
+            this.files = [];
+            this.#version += 1;
+            void this.refreshQuota();
+        });
+    }
+    /**
+     * Ask `question`, or what is in the box. Resolves once the turn settles:
+     * true if it was asked, false if it was refused, here or by the server, in
+     * which case typed words go back into the box.
+     */
+    async ask(question) {
+        const typed = question === undefined;
+        const text = (question ?? this.draft).trim();
+        if (!text)
+            return false;
+        if (this.#job)
+            return this.#message(text, typed);
+        if (this.busy || this.quota?.reached)
+            return false;
+        const files = typed ? this.files : [];
+        if (typed) {
+            this.draft = '';
+            this.files = [];
+        }
+        return this.#ask(text, files, typed);
+    }
+    /** The last question again, as a new turn: the conversation is append-only,
+     *  because the agent's transcript is. */
+    again() {
+        const last = this.turns.at(-1)?.question;
+        return last ? this.ask(last) : Promise.resolve(false);
+    }
+    /** Stop the answer being written, wherever it is being written. */
+    async stop() {
+        const id = this.conversationId;
+        if (this.#job) {
+            if (id)
+                await this.#job.stop(id).catch(() => undefined);
+            return;
+        }
+        const stream = this.#stream;
+        if (stream && this.#running) {
+            this.#running = false;
+            this.waiting = false;
+            // Before the agent has named a new conversation there is nothing to
+            // address a stop to: the stream is read on, unseen, until it does.
+            if (!id) {
+                stream.stopWanted = true;
+                return;
+            }
+            stream.controller.abort();
+            await this.#room.stop(id).catch(() => undefined);
+            return;
+        }
+        if (this.answering !== null && id) {
+            await this.#room.stop(id).catch(() => undefined);
+            clearTimeout(this.#poll);
+            await this.#settle(id, this.#generation);
+        }
+    }
+    /** Read today's allowance again. One that cannot be read is left as it was. */
+    async refreshQuota() {
+        if (!this.#room)
+            return;
+        try {
+            this.quota = await this.#room.quota();
+        }
+        catch {
+            // A counter that cannot be read costs the counter, never the ask.
+        }
+    }
+    /** Read this person's conversations. Read again after every answer once
+     *  read at all, so the list follows what they ask. */
+    async list() {
+        if (!this.#room)
+            return false;
+        try {
+            this.conversations = await this.#room.list();
+            this.listFailed = false;
+            return true;
+        }
+        catch {
+            this.listFailed = true;
+            return false;
+        }
+    }
+    async rename(id, title) {
+        const name = title.trim();
+        if (!name || !this.#room)
+            return false;
+        try {
+            await this.#room.rename(id, name);
+        }
+        catch {
+            return false;
+        }
+        const row = this.conversations?.find((c) => c.id === id);
+        if (row)
+            row.title = name;
+        return true;
+    }
+    /** Forget a conversation everywhere. The open one, forgotten, leaves a new one. */
+    async remove(id) {
+        if (!this.#room)
+            return false;
+        try {
+            await this.#room.remove(id);
+        }
+        catch {
+            return false;
+        }
+        const at = this.conversations?.findIndex((c) => c.id === id) ?? -1;
+        if (at >= 0)
+            this.conversations?.splice(at, 1);
+        if (this.conversationId === id)
+            this.new();
+        return true;
+    }
+    /** Save a conversation as the file the server names. Fetched rather than
+     *  navigated to, so one deleted a moment ago elsewhere is a false here,
+     *  not the reader's page replaced by an error body. */
+    async download(id) {
+        if (!this.#room)
+            return false;
+        try {
+            const { name, body } = await this.#room.download(id);
+            save(body, name);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Mark an answer the agent holds. False when it could not be recorded. */
+    async mark(turn, verdict) {
+        const id = this.conversationId;
+        if (!id || !this.#room?.mark || !this.#held.has(turn.id))
+            return false;
+        const position = this.turns.filter((t) => this.#held.has(t.id)).findIndex((t) => t.id === turn.id);
+        try {
+            await this.#room.mark(id, position, verdict);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    #leave() {
+        this.#generation += 1;
+        // A stop still waiting to be addressed is carried on the stream it
+        // waits on, so leaving does not lose it.
+        if (this.#stream && !this.#stream.stopWanted)
+            this.#stream.controller.abort();
+        this.#stream = null;
+        clearTimeout(this.#poll);
+        this.#watch?.abort();
+        this.#watch = null;
+        this.#watching = false;
+        this.#running = false;
+        this.answering = null;
+        this.waiting = false;
+    }
+    async #ask(text, files, typed) {
+        const room = this.#room;
+        const mine = this.#generation;
+        const stream = { controller: new AbortController(), stopWanted: false };
+        this.#stream = stream;
+        this.#turns.push({
+            id: `asked-${(minted += 1)}`,
+            question: text,
+            at: Date.now(),
+            blocks: [],
+            outcome: null,
+            citations: [],
+            suggestions: []
+        });
+        const live = this.#turns[this.#turns.length - 1];
+        const state = foldState();
+        this.#running = true;
+        this.waiting = false;
+        this.#version += 1;
+        const current = () => mine === this.#generation && this.#stream === stream;
+        let ending = null;
+        for await (const event of room.ask({
+            question: text,
+            files,
+            resume: this.conversationId,
+            signal: stream.controller.signal
+        })) {
+            const named = event.type === 'system' && event.subtype === 'init' ? event.session_id : undefined;
+            if (stream.stopWanted) {
+                if (!named)
+                    continue;
+                // The agent took the question as it named the conversation.
+                if (current()) {
+                    this.conversationId = named;
+                    this.#held.add(live.id);
+                }
+                stream.controller.abort();
+                await room.stop(named).catch(() => undefined);
+                break;
+            }
+            if (!current())
+                break;
+            if (isQueued(event)) {
+                this.waiting = true;
+                this.#version += 1;
+                continue;
+            }
+            // Waiting ends when the agent starts, and no other frame says so.
+            if (named || RUN.has(event.type))
+                this.waiting = false;
+            if (named) {
+                this.conversationId = named;
+                this.#held.add(live.id);
+                continue;
+            }
+            if (event.type === 'library_error' && event.status === 429)
+                ending = 'refused';
+            else if (event.type === 'library_error' && event.status === 409)
+                ending = 'answering';
+            else if (event.type === 'library_error' && event.dropped && this.conversationId)
+                ending = 'dropped';
+            if (ending)
+                break;
+            if (RUN.has(event.type))
+                this.#held.add(live.id);
+            fold(live, state, event);
+            this.#version += 1;
+        }
+        // Left for another conversation, or stopped and asked again: that one
+        // owns the page now.
+        if (!current())
+            return true;
+        const id = this.conversationId;
+        if (ending === 'refused' || ending === 'answering') {
+            const at = this.#turns.findIndex((t) => t.id === live.id);
+            if (at >= 0)
+                this.#turns.splice(at, 1);
+            if (typed) {
+                this.draft = text;
+                this.files = files;
+            }
+            this.#finish();
+            // Asked elsewhere and still being answered: show that instead.
+            if (ending === 'answering' && id)
+                await this.#settle(id, mine);
+            return false;
+        }
+        if (ending === 'dropped' && id) {
+            // The page lost the stream, not the turn: read where it has got to.
+            try {
+                const read = await room.read(id);
+                if (current())
+                    this.#show(read, mine);
+            }
+            catch {
+                if (current())
+                    fold(live, state, { type: 'library_error' });
+            }
+        }
+        this.#finish();
+        return true;
+    }
+    /** A turn this page streamed has settled, one way or another. */
+    #finish() {
+        this.#stream = null;
+        this.#running = false;
+        this.waiting = false;
+        this.#version += 1;
+        void this.refreshQuota();
+        if (this.conversations !== null)
+            void this.list();
+    }
+    /** A conversation as read. One still being answered shows the question in
+     *  flight with nothing of its answer, which is not written yet, and is
+     *  read again until it settles. */
+    #show(read, mine) {
+        clearTimeout(this.#poll);
+        const turns = read.turns.map((stored, index) => storedTurn(read.id, index, stored));
+        this.#held = new Set(turns.map((t) => t.id));
+        const since = epoch(read.answering_since);
+        if (since !== null) {
+            const last = read.turns.at(-1);
+            const asked = epoch(last?.at);
+            // The agent writes the question into its transcript as it takes it,
+            // so a question asked since the stamp is the one in flight. One still
+            // waiting for the agent is not there yet.
+            const inFlight = last && (asked !== null ? asked >= since : !last.answer.trim());
+            if (inFlight)
+                Object.assign(turns[turns.length - 1], { blocks: [], citations: [] });
+            else
+                turns.push({ id: `${read.id}:${turns.length}`, question: '', blocks: [], outcome: null });
+            this.#poll = setTimeout(() => void this.#settle(read.id, mine), this.#pollMs);
+        }
+        this.answering = since;
+        this.#turns = turns;
+        this.#version += 1;
+    }
+    /** Read a conversation answering out of sight again; once it has settled,
+     *  the allowance and the list have moved too. */
+    async #settle(id, mine) {
+        clearTimeout(this.#poll);
+        try {
+            const read = await this.#room.read(id);
+            if (mine !== this.#generation)
+                return;
+            this.#show(read, mine);
+            if (this.answering === null) {
+                void this.refreshQuota();
+                if (this.conversations !== null)
+                    void this.list();
+            }
+        }
+        catch {
+            if (mine === this.#generation) {
+                this.#poll = setTimeout(() => void this.#settle(id, mine), this.#pollMs);
+            }
+        }
+    }
+    #follow(id) {
+        const controller = new AbortController();
+        this.#watch = controller;
+        this.#session = new Session();
+        void this.#watchJob(id, this.#session, controller.signal);
+    }
+    /** Follow a job's stream, and follow it again whenever it may have more:
+     *  a replay folds only what is new. */
+    async #watchJob(id, session, signal) {
+        const job = this.#job;
+        while (!signal.aborted) {
+            this.#woken = false;
+            this.#watching = true;
+            try {
+                for await (const event of job.watch(id, signal)) {
+                    if (isQueued(event)) {
+                        this.waiting = true;
+                        continue;
+                    }
+                    if (RUN.has(event.type))
+                        this.waiting = false;
+                    session.apply(event);
+                }
+            }
+            catch {
+                // A transport that threw has closed its stream, as one that ended.
+            }
+            if (signal.aborted)
+                return;
+            this.#watching = false;
+            this.waiting = false;
+            await this.#idle(signal);
+        }
+    }
+    /** Until the reader says something, or the job says it carries on. */
+    async #idle(signal) {
+        const job = this.#job;
+        while (!signal.aborted && !this.#woken) {
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', done);
+                    this.#wake = null;
+                    resolve();
+                };
+                const timer = job.carriesOn ? setTimeout(done, this.#rewatchMs) : undefined;
+                this.#wake = done;
+                signal.addEventListener('abort', done, { once: true });
+            });
+            if (job.carriesOn?.())
+                return;
+        }
+    }
+    async #message(text, typed) {
+        const id = this.conversationId;
+        if (!id)
+            return false;
+        if (typed)
+            this.draft = '';
+        try {
+            await this.#job.message(id, text);
+        }
+        catch {
+            if (typed)
+                this.draft = text;
+            return false;
+        }
+        // A settled job takes it as a new run, already started when the
+        // message is accepted: its stream is watched again now.
+        this.#woken = true;
+        this.#wake?.();
+        return true;
+    }
+}
+function storedTurn(conversation, index, stored) {
+    return {
+        id: `${conversation}:${index}`,
+        question: stored.question,
+        at: epoch(stored.at) ?? undefined,
+        blocks: stored.answer ? [{ kind: 'text', index: 0, text: stored.answer }] : [],
+        outcome: null,
+        citations: stored.citations ?? []
+    };
+}
+function epoch(value) {
+    const at = value ? Date.parse(value) : NaN;
+    return Number.isNaN(at) ? null : at;
+}
+function save(body, name) {
+    const url = URL.createObjectURL(body);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = name;
+    link.click();
+    URL.revokeObjectURL(url);
+}

package/dist/client.d.ts

@@ -8,7 +8,14 @@
  * event type needs no change on either side.
  */
 import type { Citation } from './citations';
-/** One Claude Code stream event. Typed only where we branch on it. */
+/** A Claude Code message, whole. `content` is a plain string only on a user frame. */
+export interface AgentMessage {
+    id?: string;
+    content?: Array<Record<string, unknown>> | string;
+}
+/** One Claude Code stream event, or one of the library's own frames. Typed
+ *  only where we branch on it, and `type` stays open: a new event type needs
+ *  no change here. */
 export interface AgentEvent {
     type: string;
     subtype?: string;
@@ -27,11 +34,8 @@ export interface AgentEvent {
             id?: string;
         };
     };
-    /** A whole message; `content` is a plain string only on a user frame. */
-    message?: {
-        id?: string;
-        content?: Array<Record<string, unknown>> | string;
-    };
+    /** A whole message; on the library's `queued` frame, its own sentence. */
+    message?: AgentMessage | string;
     /** A user frame the CLI echoed back as the turn that consumes it starts
      *  (`--replay-user-messages`): the reader's side of a session. */
     isReplay?: boolean;
@@ -47,6 +51,12 @@ export interface AgentEvent {
     /** What a run returned under `--json-schema`, on its `result`. */
     structured_output?: unknown;
     error?: string;
+    /** On a `library_error` this layer raised: the HTTP status of a route that
+     *  answered and would not stream. 429 is a spent allowance. */
+    status?: number;
+    /** On a `library_error` this layer raised: a stream that opened and died
+     *  before its terminal frame. The turn may well go on without the page. */
+    dropped?: boolean;
     detail?: string;
     tools?: string[];
     model?: string;
@@ -59,6 +69,19 @@ export interface AgentEvent {
     items?: Citation[] | string[];
     [key: string]: unknown;
 }
+/**
+ * The library's word that an ask waits behind somebody else's: repeated at
+ * least every 30 s until the agent starts, and what keeps an idle read
+ * timeout from firing meanwhile. `message` is the library's own sentence
+ * ("another question is being answered; waiting for it to finish"); a page
+ * says it in its persona's words (`copy.waiting`).
+ */
+export interface QueuedEvent extends AgentEvent {
+    type: 'queued';
+    message: string;
+}
+/** The frame is the library's `queued`, by its type alone. */
+export declare function isQueued(event: AgentEvent): event is QueuedEvent;
 export interface AskOptions {
     question: string;
     resume?: string | null;

package/dist/client.js

@@ -7,6 +7,10 @@
  * backend sent, so the Console renders the real thing and a new Claude Code
  * event type needs no change on either side.
  */
+/** The frame is the library's `queued`, by its type alone. */
+export function isQueued(event) {
+    return event.type === 'queued';
+}
 /**
  * The request body for one ask.
  *
@@ -107,7 +111,11 @@ async function* read(open, signal, terminal) {
     // layer breaking a working consumer over a header — the terminal-frame
     // check at the end of this function catches it if it really says nothing.
     const kind = (response.headers.get('content-type') ?? '').toLowerCase();
-    if (!response.ok || !response.body || (kind && !kind.includes('text/event-stream'))) {
+    if (!response.ok) {
+        yield { type: 'library_error', status: response.status };
+        return;
+    }
+    if (!response.body || (kind && !kind.includes('text/event-stream'))) {
         yield { type: 'library_error' };
         return;
     }
@@ -146,7 +154,7 @@ async function* read(open, signal, terminal) {
         catch {
             if (signal?.aborted)
                 return;
-            yield { type: 'library_error' };
+            yield { type: 'library_error', dropped: true };
             return;
         }
         if (chunk.done)
@@ -176,5 +184,5 @@ async function* read(open, signal, terminal) {
         yield last;
     }
     if (terminal && !ended && !signal?.aborted)
-        yield { type: 'library_error' };
+        yield { type: 'library_error', dropped: true };
 }