@poodle64/librarian 2026.9.20 → 2026.9.22

package/README.md

@@ -19,6 +19,7 @@ src/lib/
   client.ts                ask() and watch(): Claude Code's OWN events, unaltered
   transcript.svelte.ts     Transcript state, the fold/segment/describe helpers
   session.svelte.ts        Session: a whole stream of runs, as turns
+  chat.svelte.ts           Chat: the page's controller, over a room's routes or a job's
   citations.ts             the Citation shape, `[n]` markers, the trust mark
   copy.ts                  every word this package says, and the host's overrides
   attachments.ts           what a reader may attach, and the limits
@@ -26,6 +27,9 @@ src/lib/
   history.svelte.ts        the browser-held conversation list, per caller
   components/
     conversation/          the whole reading surface: scroll, pill, pane, composer slot
+    conversation-list/     past conversations, newest first: reopen, rename, download, delete
+    answer-mark/           helpful or not, with a note, on the last answer
+    fair-use-notice/       today's allowance, beside the composer
     scope-statement/       what this room answers from, and what it does not hold
     agent-transcript/      one question and everything Milton did answering it
     document-pane/         the cited document, open at the cited passage
@@ -180,6 +184,116 @@ Nothing here fetches on its own behalf. The library's document read is
 authenticated, and a package that called it directly would be reaching past
 the app's proxy with a session it has no business holding.
 
+### A room's page, whole: `Chat`
+
+The hand-wired page above is the parts. A stamped room page is `Chat` over
+the room's routes, and the components bound to it:
+
+```svelte
+<script lang="ts">
+	import { Chat } from '@poodle64/librarian/chat';
+	import Conversation from '@poodle64/librarian/conversation';
+	import ConversationList from '@poodle64/librarian/conversation-list';
+	import Composer from '@poodle64/librarian/composer';
+	import FairUseNotice from '@poodle64/librarian/fair-use-notice';
+
+	const chat = new Chat(roomTransport(room)); // the app's own client, below
+	const wanted = $derived(page.url.searchParams.get('c'));
+
+	// The address names the conversation; `open` and `new` are safe here.
+	$effect(() => {
+		if (wanted && wanted !== chat.conversationId) void chat.open(wanted);
+		else if (!wanted) chat.new();
+	});
+</script>
+
+<ConversationList
+	conversations={chat.conversations}
+	failed={chat.listFailed}
+	current={chat.conversationId}
+	href={(id) => `?c=${id}`}
+	onnew={() => chat.new()}
+	onrename={(id, title) => chat.rename(id, title)}
+	ondownload={(id) => chat.download(id)}
+	ondelete={(id) => chat.remove(id)}
+/>
+<Conversation
+	turns={chat.turns}
+	running={chat.busy}
+	version={chat.version}
+	waiting={chat.waiting}
+	answering={chat.answering}
+	onregenerate={() => chat.again()}
+	onsuggest={(question) => chat.ask(question)}
+	onmark={(turn, verdict) => chat.mark(turn, verdict)}
+>
+	{#snippet composer()}
+		<FairUseNotice quota={chat.quota} />
+		<Composer
+			bind:value={chat.draft}
+			bind:files={chat.files}
+			running={chat.busy}
+			sendWhileRunning={chat.sendWhileRunning}
+			onsubmit={() => chat.ask()}
+			onstop={() => chat.stop()}
+		/>
+	{/snippet}
+</Conversation>
+```
+
+`chat.list()` reads the list once; after that it follows every answer.
+
+The transport is the app's own client over its routes, and the shapes are
+the routes' own bodies (`ConversationSummary`, `ConversationRead`,
+`StoredTurn`, `Quota`), so the stamped slice returns them as they are and
+the transport passes them through:
+
+| `RoomTransport` | Route                                                 |
+| --------------- | ----------------------------------------------------- |
+| `ask`           | `POST rooms/{room}/ask`, through `client.ask()`       |
+| `read`          | `GET conversations/{id}`                              |
+| `stop`          | `POST conversations/{id}/stop`                        |
+| `quota`         | `GET quota`                                           |
+| `list`          | this person's conversations in the room               |
+| `rename`        | `PATCH conversations/{id}`                            |
+| `remove`        | `DELETE conversations/{id}`                           |
+| `download`      | `GET conversations/{id}/export`, as `{ name, body }`  |
+| `mark`          | its answer mark, where the agent takes one (optional) |
+
+What the controller relies on the routes to say:
+
+| The route says                                                             | The page                                                                                                   |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| a `queued` frame, repeated while the ask waits                             | `waiting`, by the frame's type alone, until the agent starts: "Milton is answering another question first", beside the clock |
+| `system/init` with `session_id`                                            | `conversationId`, which the host puts in the address                                                       |
+| 429 on the ask                                                             | drops the turn, puts the words and files back in the box, reads the allowance                              |
+| 409 on the ask: the conversation is already being answered                 | drops the turn, keeps the words, shows it still answering                                                  |
+| `answering_since` on a read                                                | `answering`: the question in flight with "still answering" and its clock, read again every 5 s till it clears |
+| a stream that dropped (`library_error` with `dropped`) on a named conversation | reads it rather than failing the turn: a locked phone loses the connection, not the answer              |
+
+The library's `queued` frame is `{ type: 'queued', message }`, `message` its
+own sentence; `isQueued(event)` from `./client` narrows an event to it
+(`QueuedEvent`) for a host that reads it.
+
+A turn belongs to the server. Leaving a conversation, or the page, leaves
+its answer being written; `stop()` asks the server to end it, and before the
+agent has named a new conversation it holds the stream open, unseen, until
+it does. `again()` asks the last question as a new turn: the conversation is
+append-only because the agent's transcript is.
+
+A job is `new Chat(jobTransport)`, where `JobTransport` is its `watch`,
+`message` and `stop` (godswood's run view). The turns are `Session`'s; a
+message goes onto the run while it works and opens its stream again once it
+has settled; `carriesOn()` keeps a closed stream watched while the host says
+the job may go on by itself; `sendWhileRunning` is true.
+
+| Concern                  | How                                                                                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The answer mark          | `onmark(turn, verdict)` on `Conversation`: resolve true once recorded. Offered on the last settled answer only; without it no mark renders       |
+| Waiting, still answering | `waiting` and `answering` on `Conversation`, from the controller                                                                                 |
+| The allowance            | `FairUseNotice quota={…}` in the composer snippet: a count while there are questions left, a notice with `support_url` once there are none. Nothing for `exempt`, or a `limit` of 0 |
+| Past conversations       | `ConversationList`: newest first, `href` makes each row a link, and each act renders only when its handler is given; a delete asks first        |
+
 ### Watching a session somebody else started
 
 A session the APP started — a persona reading a document with nobody asking —
@@ -187,7 +301,10 @@ is watched rather than asked. `watch()` GETs its stream; `Session` folds it
 into turns: the prompt and every later message on the reader's side (the CLI
 echoes each one back under `--replay-user-messages`), each run's answer on the
 persona's, each settled by its own `result`. A stream without deltas is folded
-from its whole messages. Events are deduped by `uuid`, so opening the watch
+from its whole messages. A run under `--json-schema` hands in its answer by
+calling the CLI's `StructuredOutput` tool: that call is no step of the work,
+the words before it stay the answer, and what it handed in is the run's
+`outcome.structuredOutput`, the natural source of the host's `artefact`. Events are deduped by `uuid`, so opening the watch
 again after sending a message folds only what is new.
 
 ```svelte
@@ -394,8 +511,10 @@ paragraphs addressed to the model before the question renders, so a
 colleague never sees it. Pass the question as it went on the wire; the
 transcript shows what they asked.
 
-`createHistory(namespace)` from `@poodle64/librarian/history` gives each app,
-or each room inside an app, its own `localStorage` key:
+`createHistory(namespace)` from `@poodle64/librarian/history` keeps a
+browser-only list for a page with no server-side one (a page on `Chat` reads
+the server's), under its own `localStorage` key for each app, or each room
+inside an app:
 
 ```ts
 import { createHistory, titleFrom } from '@poodle64/librarian/history';
@@ -413,7 +532,7 @@ pnpm run test         # build + vitest
 pnpm run screenshots  # the state grid, real engine (see below)
 ```
 
-`docs/screenshots/` is sixteen states x three widths x both themes, taken by
+`docs/screenshots/` is twenty-three states x three widths x both themes, taken by
 `scripts/screenshots.mjs` against the console's `/librarian` lab route
 running from its own static build. The same script asserts what a screenshot
 cannot: that nothing scrolls sideways at any width, that the source pane
@@ -424,9 +543,13 @@ its question and takes the rest of the row with it, that the persona's
 between-tool narration is nowhere in the answer prose before the activity
 line is opened, that a job's artefact and the pages it read open in the
 host's own columns and never in a pane of the package's, and that the reading
-column holds its 46rem measure and stays centred at every width. It exits
-non-zero on any of them. The job states fold a stream captured from the real
-CLI (`src/test/fixtures/`).
+column holds its 46rem measure and stays centred at every width. Its `room`
+scene is `Chat` itself over a fake of the room's routes, driven: a question
+waits behind another, streams, counts against the allowance and takes a mark;
+one asked again is stopped; a conversation reopened mid-answer says so and
+settles; one is renamed and the open one deleted. It exits non-zero on any of
+them. The job states fold a stream captured from the real CLI
+(`src/test/fixtures/`).
 
 The console's `app.css` deliberately does NOT scan this package's `dist`, so
 the grid is taken in a consumer that compiles none of its Tailwind classes —
@@ -437,6 +560,9 @@ pnpm --filter @poodle64/console run build
 pnpm --filter @poodle64/librarian run screenshots
 ```
 
+Where Playwright's own Chromium will not start (NixOS), name one that does:
+`CHROMIUM=/nix/store/…-playwright-browsers/chromium-…/chrome-linux/chrome`.
+
 ## Releasing
 
 1. Change a component; bump `version` in `package.json` (CalVer).

package/dist/chat.svelte.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 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 { type AgentEvent } from './client';
+import type { Citation } from './citations';
+import { type Turn } from './transcript.svelte';
+/** One conversation in the list. */
+export interface ConversationSummary {
+    /** The agent's own session id: what resumes it, what names it in the address. */
+    id: string;
+    title: string;
+    /** ISO 8601. */
+    last_activity_at: string;
+    /** ISO 8601 while an answer is being written; null once it settles, or once
+     *  the worker writing it is gone. */
+    answering_since?: string | null;
+}
+/** One question and its answer, as the agent's transcript keeps them. */
+export interface StoredTurn {
+    /** As the reader asked it, never with a preamble. */
+    question: string;
+    answer: string;
+    /** ISO 8601, when it was asked. */
+    at?: string | null;
+    citations?: Citation[];
+}
+/** A conversation reopened. */
+export interface ConversationRead extends ConversationSummary {
+    turns: StoredTurn[];
+}
+/** Today's fair-use allowance. */
+export interface Quota {
+    /** 0: no limit. */
+    limit: number;
+    remaining: number;
+    /** Nothing is counted for this person, and nothing is shown. */
+    exempt: boolean;
+    reached: boolean;
+    /** ISO 8601. */
+    resets_at: string;
+    support_url?: string | null;
+}
+/** A reader's verdict on one answer; each one replaces the last. */
+export interface Verdict {
+    helpful: boolean;
+    note?: string | null;
+}
+export interface AskRequest {
+    question: string;
+    files: File[];
+    /** The conversation this carries on; null starts one. */
+    resume: string | null;
+    signal: AbortSignal;
+}
+/**
+ * A room's routes, as the host's own client reaches them. Every method but
+ * `ask` may reject; the controller says what failed.
+ */
+export interface RoomTransport {
+    /** `POST rooms/{room}/ask`: `client.ask()` over it, which never throws. A
+     *  refusal arrives as `library_error` with its `status`: 429 is a spent
+     *  allowance, 409 a conversation already being answered. */
+    ask(request: AskRequest): AsyncIterable<AgentEvent>;
+    /** `GET conversations/{id}`. */
+    read(id: string): Promise<ConversationRead>;
+    /** `POST conversations/{id}/stop`. */
+    stop(id: string): Promise<void>;
+    /** `GET quota`. */
+    quota(): Promise<Quota>;
+    /** This person's conversations in this room. */
+    list(): Promise<ConversationSummary[]>;
+    /** `PATCH conversations/{id}`. */
+    rename(id: string, title: string): Promise<void>;
+    /** `DELETE conversations/{id}`. */
+    remove(id: string): Promise<void>;
+    /** `GET conversations/{id}/export`: the file, and the name to save it as. */
+    download(id: string): Promise<{
+        name: string;
+        body: Blob;
+    }>;
+    /** The answer mark, where the agent takes one. `turn` is the answer's
+     *  zero-based position in the conversation. */
+    mark?(id: string, turn: number, verdict: Verdict): Promise<void>;
+}
+/** A job's routes. */
+export interface JobTransport {
+    /** `GET …/jobs/{id}/watch`: `client.watch()` over it, which never throws. */
+    watch(id: string, signal: AbortSignal): AsyncIterable<AgentEvent>;
+    /** `POST …/jobs/{id}/message`: onto the run while it works, a new run once
+     *  it has settled. */
+    message(id: string, text: string): Promise<void>;
+    /** `POST …/jobs/{id}/stop`. */
+    stop(id: string): Promise<void>;
+    /** The job may carry on by itself after its stream closes (a pipeline
+     *  still on it), so the stream is watched again. Absent, it is watched
+     *  again only when the reader sends a message. */
+    carriesOn?(): boolean;
+}
+export interface ChatOptions {
+    /** How often a conversation answering out of sight is read again. */
+    pollMs?: number;
+    /** How often a closed job is asked whether it carries on. */
+    rewatchMs?: number;
+}
+export declare class Chat {
+    #private;
+    /** 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: string;
+    files: File[];
+    /** When an answer this page is not streaming began, epoch ms: a
+     *  conversation reopened mid-answer. */
+    answering: number | null;
+    /** The agent is answering somebody else's question first. */
+    waiting: boolean;
+    /** Today's allowance; null until read, and in a job. */
+    quota: Quota | null;
+    /** The open conversation, or the job; null for a new one. The host keeps
+     *  it in the address. */
+    conversationId: string | null;
+    /** This person's conversations, as `list()` last read them; null until then. */
+    conversations: ConversationSummary[] | null;
+    listFailed: boolean;
+    constructor(transport: RoomTransport | JobTransport, options?: ChatOptions);
+    /** Every turn, in order. A live one grows in place; key on `version`. */
+    get turns(): Turn[];
+    /** Bumped on every event folded, for `Conversation`'s follow-scroll. */
+    get version(): number;
+    /** This page is streaming an answer. */
+    get running(): boolean;
+    /** Something is being answered, here or out of sight: the composer waits
+     *  and offers Stop. */
+    get busy(): boolean;
+    /** A job reads what the reader says while it works; a room waits for its answer. */
+    get sendWhileRunning(): boolean;
+    /** 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: string): Promise<boolean>;
+    /** 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(): void;
+    /**
+     * 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.
+     */
+    ask(question?: string): Promise<boolean>;
+    /** The last question again, as a new turn: the conversation is append-only,
+     *  because the agent's transcript is. */
+    again(): Promise<boolean>;
+    /** Stop the answer being written, wherever it is being written. */
+    stop(): Promise<void>;
+    /** Read today's allowance again. One that cannot be read is left as it was. */
+    refreshQuota(): Promise<void>;
+    /** Read this person's conversations. Read again after every answer once
+     *  read at all, so the list follows what they ask. */
+    list(): Promise<boolean>;
+    rename(id: string, title: string): Promise<boolean>;
+    /** Forget a conversation everywhere. The open one, forgotten, leaves a new one. */
+    remove(id: string): Promise<boolean>;
+    /** 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. */
+    download(id: string): Promise<boolean>;
+    /** Mark an answer the agent holds. False when it could not be recorded. */
+    mark(turn: Turn, verdict: Verdict): Promise<boolean>;
+}