@poodle64/librarian 2026.10.3 → 2026.10.5

package/README.md

@@ -34,11 +34,14 @@ src/lib/
     agent-transcript/      one question and everything the persona did answering it
     document-pane/         the cited document, open at the cited passage
     artefact-card/         an artefact's card, in the host's words
-    artefact-pane/         an artefact that is its answer's prose, in the column
+    artefact-pane/         an artefact that is its answer's prose, or one version of a written document, in the column
+    written-card/          a document the persona wrote: kind, pages, version, Open, and a download chip
+    source-fold/           what an answer drew on, folded: the library's numbered sources, then the web pages numbered on from them
+    visual-block/          a fenced block of a registered language: its renderer, Drawing… while it arrives, its code when invalid
     composer/              the input box: attachments, one collection control, a note, send/stop
     markdown/              sanitised, streaming-safe markdown + highlighting
-    activity-group/        a whole investigation, as one quiet line
-    tool-row/              one tool call
+    activity-group/        what the persona did, one collapsed row per step
+    tool-row/              one tool call, opening on its input and result
     thinking-row/          one thought, or one line of between-tool narration
     working/               the pre-first-token "something is happening" indicator
 ```
@@ -394,10 +397,15 @@ end that way.
 
 | Concern                | How                                                                                                                                                                  |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The persona's tools    | `describeTool(block) => ToolWords \| undefined`: the row (`verb`, `object`, `detail`), the activity line's counts (`tally`), and what it read (`source`). `undefined` leaves a call to the package's own words |
+| The persona's tools    | `describeTool(block) => ToolWords \| undefined`: the row (`verb`, `object`, `detail`) and what it read (`source`). `undefined` leaves a call to the package's own words |
 | What an answer read    | `ToolWords.source` lists under the answer, under `copy.sources`; tapping one calls `oncite`. Nothing checked it, so it carries no trust mark                          |
 | An artefact            | `turn.artefact = { title, summary }` cards under the prose once the turn settles; `isAnswer: true` is an artefact that IS the prose, and replaces it                  |
 | Opening it             | `onopenartefact(turn)` and `showing` (the turn id the host shows). Without a handler, an `isAnswer` artefact opens in `ArtefactPane` and any other offers no action |
+| Editing a question     | `Conversation`'s `onedit(position, text)` (`Chat.edit`) offers an edit control on each plain question while nothing is being answered; the turns from there on are dropped and the new question streams in at that position (`ask({ edit })`). Files are not sent again |
+| Documents it wrote     | `artefact` frames and a stored turn's `artefacts` (each with `title`, `kind`, `changes`, `pages`) become `turn.written`: the newest version of each is a card with Open and a download chip (Word where `formats` has it, else the source). The pane marks what a version changed since the one before: a "Changed since vN" line from `changes`, and a bar beside each changed block. `loadWritten(name, version)` and `writtenUrl(name, version, format)` (`Chat.loadArtefact` / `Chat.artefactUrl` over the transport) let the pane show a version: Markdown sanitised, HTML only in a `sandbox=""` frame |
+| The turn's steps       | One fold, "Read your attachment, searched the library and the web, and wrote a minute · 6 steps", composed from the steps (`stepsSummary`); it says what is happening now while the turn runs, and opens on one row per step (a search row counts what it found, a web search opens on the pages it found) |
+| Web sources            | Pages from the turn's supacrawl calls and the answer's Markdown links fold with the library's sources ("6 sources · 4 library · 2 web"), numbered on from the library's, and a link to one in the answer reads as that number's chip |
+| Drawing a fence        | `visuals` on `Conversation` is a registry keyed on a fence's language, `{ component, parse }` each; `defaultVisuals` (from `@poodle64/librarian/visuals`) draws `vega-lite` (one Vega-Lite v5 spec, in the app's tokens), `timeline` and `card`. An app passes `{ ...defaultVisuals, openui }`. A block whose closing fence has not arrived is "Drawing…", one that does not parse is its code |
 | "Answered without a source" | `copy.notHeld: ''` for a persona that answers from no sources                                                                                                     |
 | Saying something mid-run | `Composer`'s `sendWhileRunning`: while the session works the box stays open and Send sits beside Stop. For a route that reads a message while the run works; a chat leaves it off and waits for its answer |
 

package/dist/chat.svelte.d.ts

@@ -22,6 +22,7 @@
 import type { AgentEvent } from './client';
 import type { Citation } from './citations';
 import { type Artefact, type Turn } from './transcript.svelte';
+import type { Written } from './written';
 /** One conversation in the list. */
 export interface ConversationSummary {
     /** The agent's own session id: what resumes it, what names it in the address. */
@@ -47,6 +48,20 @@ export interface StoredTurn {
     collection?: string | null;
     /** Where this answer's read-only view lives while it is shared. */
     shared?: string | null;
+    /** The names of the files attached to the question. */
+    files?: string[];
+    /** The document versions written answering it, in order. */
+    artefacts?: Written[];
+    /** Every tool the agent called, in order, with its (truncated) result. */
+    steps?: StoredStep[];
+}
+/** One tool call of a stored turn. */
+export interface StoredStep {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    result: string;
+    is_error: boolean;
 }
 /** A conversation reopened. */
 export interface ConversationRead extends ConversationSummary {
@@ -79,6 +94,8 @@ export interface AskRequest {
     kind?: string;
     /** The one collection to ask, by name: `client.ask()`'s `collection`. */
     collection?: string;
+    /** The position of the question this replaces: `client.ask()`'s `edit`. */
+    edit?: number;
 }
 /**
  * A persona's chat routes, as the host's own client reaches them. Every
@@ -114,6 +131,14 @@ export interface ChatTransport {
      *  stops sharing it. Resolves to where it is read while shared, null once
      *  it is not. */
     share?(id: string, turn: number, share: boolean): Promise<string | null>;
+    /** `GET conversations/{id}/artefact`, as `source`: one version of a document
+     *  the agent wrote. */
+    loadArtefact?(id: string, name: string, version: number): Promise<{
+        text: string;
+        mediaType: string;
+    }>;
+    /** Where that version downloads as `format` (`source`, or one of its `formats`). */
+    artefactUrl?(id: string, name: string, version: number, format: string): string;
 }
 /** A job's routes. */
 export interface JobTransport {
@@ -188,6 +213,14 @@ export declare class Chat {
     /** The last question again, as a new turn: the conversation is append-only,
      *  because the agent's transcript is. Same kind, same collection. */
     again(): Promise<boolean>;
+    /**
+     * Replace the question at `position` (its place among `turns`) with `text`:
+     * the turns from there on go from the page and from the server, and the new
+     * question streams in at that position. The files that went with the old
+     * one are not sent again. Same kind and collection as the one replaced.
+     * Resolves like `ask`; a refusal puts the dropped turns back.
+     */
+    edit(position: number, text: string): 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. */
@@ -207,6 +240,13 @@ export declare class Chat {
     /** Share an answer the agent holds, or stop sharing it. False when that
      *  was not recorded. */
     share(turn: Turn, share: boolean): Promise<boolean>;
+    /** One version of a document the agent wrote in the open conversation. */
+    loadArtefact(name: string, version: number): Promise<{
+        text: string;
+        mediaType: string;
+    }>;
+    /** Where that version downloads as `format`; empty with no conversation open. */
+    artefactUrl(name: string, version: number, format: string): string;
 }
 /** A turn as read back, ready for `Conversation`: given one and no handlers,
  *  that is the read-only view of a shared answer. */

package/dist/chat.svelte.js

@@ -172,6 +172,33 @@ export class Chat {
             ? this.ask(last.question, last.kind, last.collection)
             : Promise.resolve(false);
     }
+    /**
+     * Replace the question at `position` (its place among `turns`) with `text`:
+     * the turns from there on go from the page and from the server, and the new
+     * question streams in at that position. The files that went with the old
+     * one are not sent again. Same kind and collection as the one replaced.
+     * Resolves like `ask`; a refusal puts the dropped turns back.
+     */
+    async edit(position, text) {
+        const body = text.trim();
+        const resume = this.conversationId;
+        const was = this.#turns[position];
+        if (!body || !resume || !was || this.#job || this.busy || this.quota?.reached)
+            return false;
+        const removed = this.#turns.splice(position);
+        const held = removed.filter((t) => this.#held.delete(t.id)).map((t) => t.id);
+        this.#version += 1;
+        const asked = await this.#ask(body, [], false, was.kind, was.collection, position);
+        // Refused before the server dropped anything: the page is as it was left.
+        // A conversation found already being answered was shown whole instead.
+        if (!asked && this.#turns.length === position) {
+            this.#turns.push(...removed);
+            for (const id of held)
+                this.#held.add(id);
+            this.#version += 1;
+        }
+        return asked;
+    }
     /** Stop the answer being written, wherever it is being written. */
     async stop() {
         const id = this.conversationId;
@@ -318,7 +345,7 @@ export class Chat {
         this.#running = false;
         this.answering = null;
     }
-    async #ask(text, files, typed, kind, collection) {
+    async #ask(text, files, typed, kind, collection, edit) {
         const chat = this.#chat;
         const mine = this.#generation;
         const stream = { controller: new AbortController(), stopWanted: false };
@@ -330,6 +357,7 @@ export class Chat {
             blocks: [],
             outcome: null,
             citations: [],
+            files: files.map((f) => f.name),
             kind,
             collection,
             artefact: this.#card(kind)
@@ -346,7 +374,8 @@ export class Chat {
             resume: this.conversationId,
             signal: stream.controller.signal,
             kind,
-            collection
+            collection,
+            edit
         })) {
             const named = event.type === 'system' && event.subtype === 'init' ? event.session_id : undefined;
             if (stream.stopWanted) {
@@ -415,6 +444,18 @@ export class Chat {
         this.#finish();
         return true;
     }
+    /** One version of a document the agent wrote in the open conversation. */
+    loadArtefact(name, version) {
+        const id = this.conversationId;
+        if (!id || !this.#chat?.loadArtefact)
+            return Promise.reject(new Error('no artefact'));
+        return this.#chat.loadArtefact(id, name, version);
+    }
+    /** Where that version downloads as `format`; empty with no conversation open. */
+    artefactUrl(name, version, format) {
+        const id = this.conversationId;
+        return id && this.#chat?.artefactUrl ? this.#chat.artefactUrl(id, name, version, format) : '';
+    }
     /** What a turn of `kind` opens, if the host says it opens anything. */
     #card(kind) {
         return kind ? this.#artefact?.(kind) : undefined;
@@ -547,13 +588,26 @@ export class Chat {
 /** A turn as read back, ready for `Conversation`: given one and no handlers,
  *  that is the read-only view of a shared answer. */
 export function storedTurn(conversation, index, stored) {
+    const blocks = (stored.steps ?? []).map((step, at) => ({
+        kind: 'tool',
+        index: at,
+        id: step.id,
+        name: step.name,
+        rawInput: JSON.stringify(step.input ?? {}),
+        result: step.result,
+        isError: step.is_error
+    }));
+    if (stored.answer)
+        blocks.push({ kind: 'text', index: blocks.length, text: stored.answer });
     return {
         id: `${conversation}:${index}`,
         question: stored.question,
         at: epoch(stored.at) ?? undefined,
-        blocks: stored.answer ? [{ kind: 'text', index: 0, text: stored.answer }] : [],
+        blocks,
         outcome: null,
         citations: stored.citations ?? [],
+        files: stored.files ?? [],
+        written: stored.artefacts ?? [],
         kind: stored.kind ?? undefined,
         collection: stored.collection ?? undefined,
         shared: stored.shared ?? undefined

package/dist/client.d.ts

@@ -71,6 +71,9 @@ export interface AskOptions {
     /** The one collection this question is asked of, by name. Absent asks
      *  across every collection the person may read. */
     collection?: string;
+    /** The position (0-based) of the person's question this one replaces: the
+     *  server drops that turn and every one after it. Needs `resume`. */
+    edit?: number;
     /** Files the persona reads for this question. Switches the request to multipart. */
     files?: File[];
     /** What kind of turn this ask should become. Absent means an ordinary

package/dist/client.js

@@ -29,7 +29,8 @@ function requestInit(options, signal) {
                 question: options.question,
                 resume: options.resume ?? null,
                 collection: options.collection,
-                kind: options.kind
+                kind: options.kind,
+                edit: options.edit
             }),
             signal
         };
@@ -44,6 +45,8 @@ function requestInit(options, signal) {
         form.append('files[]', file, file.name);
     if (options.kind)
         form.append('kind', options.kind);
+    if (options.edit !== undefined)
+        form.append('edit', String(options.edit));
     return { method: 'POST', credentials: 'include', body: form, signal };
 }
 /**

package/dist/components/activity-group/activity-group.svelte

@@ -1,21 +1,24 @@
 <!--
-  A whole investigation, as ONE line the reader can open.
+  What the persona did before it answered, folded behind one line.
 
-  Not a stack. Fifteen tool rows between the question and the first word of the
-  answer is the machinery on show, and a running commentary of "Let me
-  check…" is worse: it narrates a mechanism the persona is under instruction
-  never to mention. So there is exactly one row in every state — "Working…"
-  while it runs, a count of what was done once it settles — and the steps are
-  behind a disclosure for the reader who wants them.
+  The line is a sentence composed from the steps ("Read your attachment,
+  searched the library and the web, and wrote a minute · 6 steps"), and while
+  the turn runs it says what is happening now. It opens on one row per step,
+  in order, the way Claude Code's own panel lists them: each says what the step
+  did in a reader's words and opens on what went in and what came back.
 
-  That commentary is a step in here too. It reaches the caller as an ordinary
-  `text` block, not a `thinking` one, so `segment()` re-homes any text with a
-  tool call still to come into this group; it renders as a ThinkingRow beside
-  the tools, folded like the rest.
+  The persona's between-tool commentary is a step in here as well. It reaches
+  the caller as an ordinary `text` block, not a `thinking` one, so `segment()`
+  re-homes any text with a tool call still to come into this group; it renders
+  as a ThinkingRow beside the tools, folded like the rest.
 -->
 <script lang="ts">
-	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
-	import { summariseActivity, type ActivityGroup } from '../../transcript.svelte';
+	import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+	import ChevronUpIcon from '@lucide/svelte/icons/chevron-up';
+	import type { ActivityGroup } from '../../transcript.svelte';
+	import { resolveCopy, type ChatCopy } from '../../copy';
+	import { stepsNow, stepsSummary } from '../../steps';
+	import type { Written } from '../../written';
 	import ToolRow from '../tool-row/tool-row.svelte';
 	import ThinkingRow from '../thinking-row/thinking-row.svelte';
 
@@ -23,43 +26,45 @@
 		group: ActivityGroup;
 		/** True while this group is the live one. */
 		live: boolean;
+		/** The documents the turn wrote: a step that wrote one says its kind. */
+		written?: Written[];
+		copy?: Partial<ChatCopy>;
 	}
 
-	let { group, live }: Props = $props();
-	let expanded = $state(false);
+	let { group, live, written = [], copy }: Props = $props();
+	let open = $state(false);
 
-	// A live group has nothing to count yet, so counting it reads as "0
-	// searches" flickering up to the real number.
-	const label = $derived(live ? 'Working…' : summariseActivity(group));
+	const words = $derived(resolveCopy(copy));
+	const summary = $derived(stepsSummary(group.steps, written, words));
+	const now = $derived(stepsNow(group.steps, written, words));
 </script>
 
-<div>
+<div class="ds-lib-steps">
 	<button
 		type="button"
-		class="ds-lib-activity-toggle"
-		onclick={() => (expanded = !expanded)}
-		aria-expanded={expanded}
+		class="ds-lib-steps-head"
+		onclick={() => (open = !open)}
+		aria-expanded={open}
 	>
-		<span class="ds-lib-activity-chevron" class:is-open={expanded}>
-			<ChevronRightIcon size={14} />
+		<span class="ds-lib-steps-line">
+			{#if live}
+				<span class="ds-lib-steps-now">{now}</span>
+			{:else}
+				{summary.sentence}<span class="ds-lib-steps-trail">{` · ${summary.trail}`}</span>
+			{/if}
+		</span>
+		<span class="ds-lib-steps-chevron" aria-hidden="true">
+			{#if open}<ChevronUpIcon size={15} />{:else}<ChevronDownIcon size={15} />{/if}
 		</span>
-		{#if live}
-			<span class="ds-lib-activity-dot"></span>
-		{/if}
-		<span>{label}</span>
 	</button>
-	{#if expanded}
-		<div class="ds-lib-activity-steps">
-			{#each group.steps as step (step.block.index)}
+
+	{#if open}
+		<div class="ds-lib-steps-rows">
+			{#each group.steps as step, i (step.block.index)}
 				{#if step.block.kind === 'tool'}
-					<ToolRow
-						block={step.block}
-						repeats={step.repeats}
-						words={step.words}
-						running={live}
-					/>
+					<ToolRow block={step.block} words={step.words} running={live} {copy} />
 				{:else}
-					<ThinkingRow block={step.block} active={false} />
+					<ThinkingRow block={step.block} active={live && i === group.steps.length - 1} {copy} />
 				{/if}
 			{/each}
 		</div>
@@ -67,67 +72,57 @@
 </div>
 
 <style>
-	.ds-lib-activity-toggle {
+	.ds-lib-steps-head {
 		display: flex;
-		align-items: center;
-		gap: 0.375rem;
+		width: 100%;
+		align-items: flex-start;
+		gap: 0.5rem;
 		border: 0;
 		background: none;
-		padding: 0;
+		padding: 0.25rem 0;
 		color: var(--ds-color-muted-foreground);
 		font: inherit;
 		font-size: 0.875rem;
-		line-height: 1.25rem;
+		line-height: 1.375rem;
+		text-align: start;
 		cursor: pointer;
-		transition: color 150ms ease;
 	}
 
-	.ds-lib-activity-toggle:hover {
+	.ds-lib-steps-head:hover {
 		color: var(--ds-color-foreground);
 	}
 
-	.ds-lib-activity-chevron {
-		display: flex;
-		flex: none;
-		transition: transform 150ms ease;
+	.ds-lib-steps-head:focus-visible {
+		outline: 2px solid var(--ds-color-ring);
+		outline-offset: 2px;
 	}
 
-	.ds-lib-activity-chevron.is-open {
-		transform: rotate(90deg);
+	.ds-lib-steps-line {
+		flex: 1;
 	}
 
-	.ds-lib-activity-dot {
-		width: 0.375rem;
-		height: 0.375rem;
+	.ds-lib-steps-now {
+		color: var(--ds-color-foreground);
+		font-weight: 500;
+	}
+
+	.ds-lib-steps-trail {
+		font-size: var(--ds-text-2xs);
+		opacity: 0.8;
+	}
+
+	.ds-lib-steps-chevron {
+		display: flex;
 		flex: none;
-		border-radius: var(--ds-radius-full);
-		background: var(--ds-color-status-info);
-		animation: ds-lib-activity-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+		padding-top: 0.25rem;
 	}
 
-	.ds-lib-activity-steps {
+	.ds-lib-steps-rows {
 		display: flex;
 		flex-direction: column;
-		gap: 0.375rem;
-		margin-top: 0.5rem;
-		margin-inline-start: 0.4375rem;
+		gap: 0.125rem;
+		margin-top: 0.25rem;
 		border-inline-start: 1px solid var(--ds-color-border);
 		padding-inline-start: 0.75rem;
 	}
-
-	@keyframes ds-lib-activity-pulse {
-		50% {
-			opacity: 0.4;
-		}
-	}
-
-	@media (prefers-reduced-motion: reduce) {
-		.ds-lib-activity-dot {
-			animation: none;
-		}
-
-		.ds-lib-activity-chevron {
-			transition: none;
-		}
-	}
 </style>

package/dist/components/activity-group/activity-group.svelte.d.ts

@@ -1,8 +1,13 @@
-import { type ActivityGroup } from '../../transcript.svelte';
+import type { ActivityGroup } from '../../transcript.svelte';
+import { type ChatCopy } from '../../copy';
+import type { Written } from '../../written';
 interface Props {
     group: ActivityGroup;
     /** True while this group is the live one. */
     live: boolean;
+    /** The documents the turn wrote: a step that wrote one says its kind. */
+    written?: Written[];
+    copy?: Partial<ChatCopy>;
 }
 declare const ActivityGroup: import("svelte").Component<Props, {}, "">;
 type ActivityGroup = ReturnType<typeof ActivityGroup>;