@vincemakes/kiso-web 0.0.0-stage → 0.52.0

package/dist/main/settings.js

@@ -0,0 +1,175 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { applyEffortDeclarations, contextWindowOf, demoScript, authForProfile, effortOptions, loadUserConfig, mergeConfigs, preferences, profileAvailable, rememberEffort, startingEffort, } from "@vincemakes/kiso-code/config";
+import { MODE_LABEL, OFFERED_MODES } from "@vincemakes/kiso-code/policy";
+import { fauxSkip } from "./faux.js";
+import { storeKey } from "./login.js";
+const MAX_RECENT = 10;
+const isTier = (value) => OFFERED_MODES.some((m) => m === value);
+export class Settings {
+    #file;
+    /** a scripted model (the proofs); the shared configuration is then not read */
+    #fixed;
+    /** the tier a Work starts with when nothing was set for it */
+    #default;
+    /** the scripted tour, once started: a factory for its model (the demo script after the turns a Work has used) */
+    #demo = null;
+    constructor(home, fixed, mode) {
+        this.#file = join(home, "desktop.json");
+        this.#fixed = fixed;
+        const saved = this.#read().mode;
+        this.#default = isTier(saved) ? saved : mode;
+    }
+    /** The tier of one Work (read by the policy on every decision), else the one new Works start with. */
+    tierOf(sessionId) {
+        const own = sessionId === undefined ? undefined : this.#read().tiers?.[sessionId];
+        return isTier(own) ? own : this.#default;
+    }
+    /** Folders the person picked, newest first; and one more picked now. */
+    recents() {
+        return this.#read().recent ?? [];
+    }
+    addRecent(path) {
+        this.write({ recent: [path, ...this.recents().filter((p) => p !== path)].slice(0, MAX_RECENT) });
+    }
+    /** Start the scripted tour: no key, the terminal's own demo script, for Works opened from now on. */
+    async startDemo() {
+        const { createFauxProvider } = await import("@vincemakes/kiso-evals");
+        this.#demo = (skip) => ({ kind: "adapter", adapter: createFauxProvider(demoScript().slice(skip)), model: "demo", route: "adapter" });
+    }
+    #read() {
+        try {
+            return JSON.parse(readFileSync(this.#file, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Merge into `desktop.json` (the folder memory lives there too). */
+    write(patch) {
+        try {
+            mkdirSync(join(this.#file, ".."), { recursive: true, mode: 0o700 });
+            writeFileSync(this.#file, `${JSON.stringify({ ...this.#read(), ...patch })}\n`, { mode: 0o600 });
+        }
+        catch {
+            // a read-only home only loses the memory
+        }
+    }
+    lastFolder() {
+        return this.#read().lastFolder;
+    }
+    #config() {
+        const merged = mergeConfigs(loadUserConfig(), null);
+        applyEffortDeclarations(merged);
+        return merged;
+    }
+    /** The profile in use: the person's pick if it still exists, else the configuration's own default. */
+    #chosen(config) {
+        const models = config.models ?? {};
+        const picked = this.#read().profile;
+        if (picked !== undefined && models[picked] !== undefined)
+            return picked;
+        return config.model !== undefined && models[config.model] !== undefined ? config.model : null;
+    }
+    /** The model a Work opened now runs on; throws, in words, when none can. */
+    model(ctx) {
+        if (this.#fixed !== null)
+            return this.#fixed;
+        if (this.#demo !== null)
+            return this.#demo(ctx === undefined ? 0 : fauxSkip(ctx.sessionsDir, ctx.sessionId));
+        const config = this.#config();
+        const name = this.#chosen(config);
+        if (name === null)
+            throw new Error("no model is configured: add a profile to ~/.kiso/config.json (see the terminal's docs) and choose it in Settings");
+        const profile = config.models[name];
+        const auth = authForProfile(name, profile);
+        const effort = startingEffort(profile, preferences().effort?.[name]);
+        return {
+            kind: "profile",
+            name,
+            profile,
+            auth: auth.type === "oauth" ? { type: "oauth", providerId: auth.providerId } : { type: "api-key", apiKey: auth.apiKey },
+            contextWindow: contextWindowOf(profile, config) ?? undefined,
+            ...(effort !== null ? { reasoning: { thinking: "default", effort } } : {}),
+        };
+    }
+    /** The person's own test-runner commands (`checks` in the configuration), for the compaction phase rule. */
+    checks() {
+        return Object.values(this.#config().checks ?? {});
+    }
+    /** The names of the environment variables that hold a key: no shell child may inherit them. */
+    secretEnvNames() {
+        return Object.values(this.#config().models ?? {}).flatMap((p) => (p.apiKeyEnv === undefined ? [] : [p.apiKeyEnv]));
+    }
+    /** What the home screen should offer: nothing, a key for a profile, a profile to add, or the tour already on. */
+    #setup(config, name) {
+        if (this.#fixed !== null)
+            return "ready";
+        if (this.#demo !== null)
+            return "demo";
+        const models = config.models ?? {};
+        if (Object.keys(models).length === 0)
+            return "noprofile";
+        return name !== null && profileAvailable(models[name]) ? "ready" : "signin";
+    }
+    /** Store a key for a profile (the terminal's credential file); a sign-in ends the tour. */
+    saveKey(profile, key) {
+        storeKey(this.#config().models?.[profile], key);
+        this.#demo = null;
+        if (this.#read().profile === undefined)
+            this.write({ profile });
+    }
+    snapshot(session) {
+        const config = this.#config();
+        const models = config.models ?? {};
+        const name = this.#chosen(config);
+        const profile = name === null ? undefined : models[name];
+        const levels = profile === undefined ? null : effortOptions(profile);
+        return {
+            profiles: Object.entries(models).map(([n, p]) => ({ name: n, model: p.model, available: profileAvailable(p) })),
+            profile: name,
+            effort: levels === null || name === null ? null : { ...levels, current: startingEffort(profile, preferences().effort?.[name]) },
+            mode: this.tierOf(session),
+            setup: this.#setup(config, name),
+            modes: OFFERED_MODES.map((value) => ({ value, label: MODE_LABEL[value] })),
+            signIn: name === null ? { ok: false, text: "No model is configured." } : signInOf(name, profile),
+        };
+    }
+    apply(patch) {
+        const config = this.#config();
+        if (patch.profile !== undefined && config.models?.[patch.profile] !== undefined) {
+            this.write({ profile: patch.profile });
+            // choosing a profile that can run ends the tour
+            if (profileAvailable(config.models[patch.profile]))
+                this.#demo = null;
+        }
+        const name = patch.profile ?? this.#chosen(config);
+        const profile = name === null ? undefined : config.models?.[name];
+        if (patch.effort !== undefined && name !== null && profile !== undefined && effortOptions(profile)?.levels.includes(patch.effort) === true)
+            rememberEffort(name, patch.effort);
+        if (isTier(patch.mode)) {
+            if (patch.session === undefined) {
+                this.#default = patch.mode;
+                this.write({ mode: patch.mode });
+            }
+            else if (/^[A-Za-z0-9._-]+$/.test(patch.session))
+                this.write({ tiers: { ...this.#read().tiers, [patch.session]: patch.mode } });
+        }
+    }
+}
+/** Where a profile's sign-in comes from, in words; the secret is never part of it. */
+function signInOf(name, profile) {
+    try {
+        const auth = authForProfile(name, profile);
+        if (auth.type === "oauth")
+            return { ok: true, text: `Signed in with ${auth.providerId} (shared with the terminal)` };
+        if (auth.source === "store")
+            return { ok: true, text: "Signed in: a key stored by the terminal's login" };
+        if (auth.source === "env")
+            return { ok: true, text: `Using the key in the environment variable ${profile.apiKeyEnv ?? ""}` };
+        return { ok: true, text: "This endpoint needs no key" };
+    }
+    catch (error) {
+        return { ok: false, text: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/main/space.js

@@ -0,0 +1,164 @@
+import { realpathSync } from "node:fs";
+import { SessionStore } from "@vincemakes/kiso-runtime";
+import { createSessionService, toWireEvent } from "@vincemakes/kiso-server";
+import { createHttpHandler } from "@vincemakes/kiso-server/http";
+import { createWebAgent, routeOf } from "./agent.js";
+import { createTaskHub, rowsOf } from "./tasks.js";
+import { runTotals, usageFrameAt } from "./usage.js";
+import { webSanitize } from "./sanitize.js";
+import { TimeIndex } from "./times.js";
+import { artifactsOf, LogImages } from "./artifacts.js";
+const HEAD_LINES = 12;
+const DELTAS = new Set(["thinking", "text_delta"]);
+export function createSpace(options) {
+    const store = new SessionStore(options.dir);
+    const tasks = createTaskHub(options.dir);
+    const route = () => {
+        try {
+            return routeOf(options.model());
+        }
+        catch {
+            return "unknown";
+        }
+    };
+    const opened = new Set();
+    const service = createSessionService({
+        store,
+        open: async (sessionId) => {
+            opened.add(sessionId);
+            return createWebAgent({
+                store,
+                workspace: options.workspace,
+                model: options.model({ sessionId, sessionsDir: options.dir }),
+                tier: () => options.tierOf(sessionId),
+                sessionId,
+                checkRunners: options.checkRunners(),
+                tasks,
+                ...(options.secretEnvNames !== undefined ? { secretEnvNames: options.secretEnvNames } : {}),
+                ...(options.toolLimits !== undefined ? { toolLimits: options.toolLimits } : {}),
+                onSession: (sessionId, session) => {
+                    // the model hears how a task ended; nothing wakes an idle session
+                    session.useTasks(tasks.managerFor(sessionId), { wake: false });
+                },
+            });
+        },
+    });
+    const windowOf = () => {
+        try {
+            const m = options.model();
+            return m.kind === "profile" ? (m.contextWindow ?? null) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const times = new TimeIndex(store);
+    const augment = (event, sessionId) => {
+        const frames = [];
+        // when it happened: for every wire event but the two delta types, which are too many
+        if (!DELTAS.has(event.type) && toWireEvent(event) !== null) {
+            const at = { seq: event.seq, ts: times.at(sessionId, event.seq) };
+            frames.push({ event: "at", data: at });
+        }
+        frames.push(...derived(event, sessionId));
+        return frames;
+    };
+    /** The tool, input and execution start of the call a result answers, from the log before it. */
+    const callOf = (sessionId, callId) => {
+        let call = null;
+        let startedAt = null;
+        for (const e of service.events(sessionId)) {
+            if (e.type === "tool_call_end" && e.callId === callId)
+                call = { name: e.name, input: e.input };
+            if (e.type === "tool_execution_started" && e.callId === callId)
+                startedAt = times.at(sessionId, e.seq);
+        }
+        return call === null ? null : { ...call, startedAt };
+    };
+    const realWorkspace = () => {
+        try {
+            return realpathSync(options.workspace);
+        }
+        catch {
+            return options.workspace;
+        }
+    };
+    const derived = (event, sessionId) => {
+        if (event.type === "usage") {
+            const frame = usageFrameAt(service.events(sessionId), event.seq, route());
+            return frame === null ? [] : [{ event: "usage", data: { ...frame, window: windowOf() } }];
+        }
+        if (event.type === "terminal") {
+            const totals = runTotals(service.events(sessionId), event.seq, route());
+            return totals === null ? [] : [{ event: "run_usage", data: { seq: event.seq, ...totals } }];
+        }
+        if (event.type === "tool_result") {
+            const artifacts = artifactsOf(event, sessionId, callOf(sessionId, event.callId), realWorkspace());
+            const text = typeof event.content === "string" ? event.content : event.content.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("\n");
+            const lines = text.split("\n");
+            const frame = {
+                seq: event.seq,
+                callId: event.callId,
+                isError: event.isError,
+                head: lines.slice(0, HEAD_LINES),
+                lines: lines.length,
+                bytes: Buffer.byteLength(text),
+                truncated: lines.length > HEAD_LINES,
+                ...((event.tags ?? []).includes("created") ? { created: true } : {}),
+                ...(artifacts.length > 0 ? { artifacts } : {}),
+            };
+            return [{ event: "tool_output", data: frame }];
+        }
+        return [];
+    };
+    // The tasks frame: not tied to any event (a command can end while nothing
+    // else happens), so it is the host's own source, polled while a stream is open.
+    const frames = (sessionId, push) => {
+        let last = "";
+        const tick = () => {
+            try {
+                const rows = rowsOf(tasks.managerFor(sessionId));
+                // elapsed time of a running task changes every tick; the state does not
+                const key = JSON.stringify(rows.map((r) => [r.id, r.label]));
+                const running = rows.some((r) => r.endedAt === null);
+                if (key !== last || running) {
+                    last = key;
+                    const frame = { at: Date.now(), tasks: rows };
+                    push({ event: "tasks", data: frame });
+                }
+            }
+            catch {
+                // a corrupt journal is the terminal's to report; the stream goes on
+            }
+        };
+        tick();
+        const timer = setInterval(tick, 1_000);
+        timer.unref();
+        return () => clearInterval(timer);
+    };
+    const handler = createHttpHandler(service, {
+        prefix: options.prefix,
+        // the host's guard has already run: bearer token, Host and Origin
+        authorize: () => true,
+        augment,
+        frames,
+        projection: { exposeThinking: options.exposeThinking, ...(options.sanitizer === "default" ? {} : { sanitize: webSanitize }) },
+        ...(options.keepaliveMs !== undefined ? { keepaliveMs: options.keepaliveMs } : {}),
+    });
+    return {
+        key: options.key,
+        workspace: options.workspace,
+        dir: options.dir,
+        store,
+        service,
+        tasks,
+        images: new LogImages(options.dir),
+        handler,
+        opened: () => opened,
+        drain: (graceMs) => service.drain(graceMs),
+        close: async () => {
+            await tasks.close();
+            store.closeAll();
+        },
+    };
+}

package/dist/main/tasks.js

@@ -0,0 +1,88 @@
+/**
+ * Background tasks (ADR-0058) for the web app's sessions.
+ *
+ * THE ONE FILE that reaches behind the public surface: the TaskManager and
+ * its journal types are exported only from `@vincemakes/kiso-runtime/internal`
+ * today. scripts/check-imports.mjs allows exactly this file to do so, and
+ * the spike report proposes the root export that removes the exception.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { TaskManager } from "@vincemakes/kiso-runtime/internal";
+import { processTaskBackend } from "@vincemakes/kiso-tools-node";
+export { TaskManager };
+export function createTaskHub(storeRoot) {
+    // the runner is started with process.execPath: the host is plain node, so the runner is too
+    const backend = processTaskBackend();
+    const managers = new Map();
+    const managerFor = (sessionId) => {
+        let manager = managers.get(sessionId);
+        if (manager === undefined) {
+            manager = new TaskManager({ root: join(storeRoot, `${sessionId}.tasks`), backend });
+            manager.observe();
+            managers.set(sessionId, manager);
+        }
+        return manager;
+    };
+    return {
+        // the manager satisfies ShellTasks structurally (tools-node takes no runtime dependency)
+        shellTasks: (sessionId) => (sessionId === undefined ? undefined : managerFor(sessionId)),
+        managerFor,
+        close: async () => {
+            for (const manager of managers.values()) {
+                await manager.stopAll("exit", 2_000, "moved");
+                manager.close();
+            }
+        },
+    };
+}
+/** A task's state in a person's words (the terminal's `/tasks` wording). */
+export function stateLabel(task) {
+    const s = task.state;
+    switch (s.kind) {
+        case "starting":
+            return "starting";
+        case "not_run":
+            return "never ran";
+        case "running":
+            return task.stoppedBy !== undefined ? "stopping" : s.ready ? "ready" : "running";
+        case "unknown":
+            return "lost track";
+        case "ended":
+            if (s.stopped)
+                return "stopped";
+            if (s.error !== undefined)
+                return "failed to start";
+            return s.exitCode === 0 ? "exited 0" : s.exitCode !== null ? `failed ${s.exitCode}` : `ended ${s.signal ?? ""}`.trim();
+    }
+}
+/** The last lines of a task's output file (read from its end, never whole). */
+function tailOf(path, lines = 4) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, 2048);
+            const buf = Buffer.alloc(length);
+            readSync(fd, buf, 0, length, size - length);
+            return buf.toString("utf8").split("\n").filter((l) => l !== "").slice(-lines);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+}
+export function rowsOf(manager, now = Date.now()) {
+    return manager.list().map((t) => ({
+        id: t.id,
+        label: stateLabel(t),
+        command: t.command.split("\n")[0],
+        startedAt: t.startedAt,
+        endedAt: t.endedAt ?? null,
+        elapsedMs: (t.endedAt ?? now) - t.startedAt,
+        tail: tailOf(t.outputPath),
+    }));
+}

package/dist/main/times.js

@@ -0,0 +1,28 @@
+/**
+ * When each durable event happened. The wire events carry no timestamp; the
+ * durable records do (`StoreRecord.ts`), so durations ("thought for N s",
+ * a step's time, the footer's duration) are read here and sent as `at`
+ * frames. A session's records are read once; events that arrive later are
+ * stamped on arrival, which is the moment the store wrote them to within
+ * a few milliseconds.
+ */
+export class TimeIndex {
+    #store;
+    #bySession = new Map();
+    constructor(store) {
+        this.#store = store;
+    }
+    at(sessionId, seq) {
+        let known = this.#bySession.get(sessionId);
+        if (known === undefined) {
+            known = new Map(this.#store.load(sessionId).map((r) => [r.event.seq, r.ts]));
+            this.#bySession.set(sessionId, known);
+        }
+        let ts = known.get(seq);
+        if (ts === undefined) {
+            ts = Date.now();
+            known.set(seq, ts);
+        }
+        return ts;
+    }
+}

package/dist/main/usage.js

@@ -0,0 +1,83 @@
+import { canonicalizeUsage } from "@vincemakes/kiso-runtime";
+import { cacheRate } from "../shared/frames.js";
+/**
+ * The run's usage, read off the durable log — `usage` is not on the wire.
+ *
+ * The same two rules the terminal's ledger states (apps/cli chat.ts,
+ * turnUsageLedger): a CALL is its LATEST report (a gateway may report one
+ * request twice), a RUN is the sum over its calls, and an unmeasured term
+ * makes the sum unmeasured. `stop` ends a call; `terminal` ends the run.
+ * The input is the canonical FRESH count, so the cache rate
+ * cache / (fresh + cache) can never pass 100%.
+ */
+const sum = (a, b) => (a === null || b === null ? null : a + b);
+function fold(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return { fresh: sum(a.fresh, b.fresh), output: sum(a.output, b.output), cacheRead: sum(a.cacheRead, b.cacheRead), costUsd: sum(a.costUsd, b.costUsd), known: a.known && b.known };
+}
+/** One durable usage event as numbers; `route` is the adapter identity the
+ *  canonical mapping keys on ("openai-compat", "anthropic", "adapter"). */
+export function callNumbers(route, ev) {
+    const c = canonicalizeUsage(route, ev);
+    return { fresh: c.input, output: c.output, cacheRead: ev.cacheRead === null ? null : c.cacheRead, costUsd: c.costUsd, known: ev.known };
+}
+/** The frame for the usage event at `seq`: the call, and the run so far. */
+export function usageFrameAt(events, seq, route) {
+    let settled = null;
+    let inFlight = null;
+    let calls = 0;
+    for (const ev of events) {
+        if (ev.seq > seq)
+            break;
+        if (ev.type === "terminal") {
+            settled = null;
+            inFlight = null;
+            calls = 0;
+        }
+        else if (ev.type === "stop") {
+            settled = fold(settled, inFlight);
+            inFlight = null;
+        }
+        else if (ev.type === "usage") {
+            if (inFlight === null)
+                calls += 1;
+            inFlight = callNumbers(route, ev);
+            if (ev.seq === seq) {
+                const turn = fold(settled, inFlight);
+                return { seq, window: null, call: inFlight, turn: { ...turn, cacheRate: cacheRate(turn.fresh, turn.cacheRead), calls } };
+            }
+        }
+    }
+    return null;
+}
+/** The run that ended at the terminal `seq`: its totals. */
+export function runTotals(events, terminalSeq, route) {
+    let settled = null;
+    let inFlight = null;
+    let calls = 0;
+    for (const ev of events) {
+        if (ev.seq > terminalSeq)
+            break;
+        if (ev.type === "terminal") {
+            if (ev.seq === terminalSeq) {
+                const turn = fold(settled, inFlight);
+                return turn === null ? null : { ...turn, cacheRate: cacheRate(turn.fresh, turn.cacheRead), calls };
+            }
+            settled = inFlight = null;
+            calls = 0;
+        }
+        else if (ev.type === "stop") {
+            settled = fold(settled, inFlight);
+            inFlight = null;
+        }
+        else if (ev.type === "usage") {
+            if (inFlight === null)
+                calls += 1;
+            inFlight = callNumbers(route, ev);
+        }
+    }
+    return null;
+}

package/dist/shared/files.js

@@ -0,0 +1,2 @@
+/** What the read-only file doors answer (`/desk/fs/tree`, `/desk/fs/file`) and the task-log door. Nothing here leaves the Work's folder. */
+export {};

package/dist/shared/frames.js

@@ -0,0 +1,13 @@
+/**
+ * The web app's own frames — what the host adds beside the wire events on
+ * the same stream (`event: <name>` without an `id:`). None of them is
+ * durable: a reconnecting client is replayed the wire events and gets the
+ * frames of the events it missed again, and `tasks` afresh.
+ */
+/** cache / (fresh + cache), as a percentage; null when unmeasured. */
+export function cacheRate(fresh, cache) {
+    if (fresh === null || cache === null)
+        return null;
+    const total = fresh + cache;
+    return total > 0 ? (cache / total) * 100 : null;
+}

package/dist/shared/history.js

@@ -0,0 +1,5 @@
+/**
+ * The history of Works across every project folder: what `GET /desk/history`
+ * answers. A Work is one session; it belongs to the folder it was started in.
+ */
+export {};

package/dist/shared/settings.js

@@ -0,0 +1,2 @@
+/** What `GET /desk/settings` answers and `POST /desk/settings` takes. No credential is ever in it: only where the sign-in comes from. */
+export {};

package/dist/shared/thinking.js

@@ -0,0 +1,65 @@
+/**
+ * Thinking on the wire arrives as many small `thinking` deltas. The stream
+ * the owner approved shows ONE line that pages to each paragraph's first
+ * sentence and opens to the full text. This is that pager, as a pure
+ * function over the deltas — nothing in the protocol needs to change.
+ *
+ *   push(text)  → what became known: a paragraph's `line` (its first
+ *                 sentence, once that sentence is complete), or a closed
+ *                 `paragraph` (its full text, once a blank line follows)
+ *   flush()     → the open paragraph at the end of the thinking
+ *
+ * A paragraph ends at a blank line. Its first sentence ends at the first
+ * `.`, `!` or `?` followed by whitespace, at a line break, or at the end of
+ * the paragraph when none comes.
+ */
+const SENTENCE_END = /^(.*?[.!?])\s/s;
+export class ThinkingPager {
+    #buf = "";
+    #paragraph = 0;
+    #lineSent = false;
+    push(text) {
+        this.#buf += text;
+        const events = [];
+        for (;;) {
+            const gap = /\n[ \t]*\n/.exec(this.#buf);
+            if (gap === null)
+                break;
+            const body = this.#buf.slice(0, gap.index);
+            this.#buf = this.#buf.slice(gap.index + gap[0].length);
+            if (body.trim() !== "")
+                this.#close(body, events);
+        }
+        this.#firstLine(events);
+        return events;
+    }
+    flush() {
+        const events = [];
+        if (this.#buf.trim() !== "")
+            this.#close(this.#buf, events);
+        this.#buf = "";
+        return events;
+    }
+    #firstLine(events) {
+        if (this.#lineSent)
+            return;
+        const trimmed = this.#buf.replace(/^\s+/, "");
+        const nl = trimmed.indexOf("\n");
+        const m = SENTENCE_END.exec(trimmed);
+        const cut = m !== null ? m[1].length : -1;
+        const end = nl !== -1 && (cut === -1 || nl < cut) ? nl : cut;
+        if (end !== -1 && end > 0) {
+            this.#lineSent = true;
+            events.push({ kind: "line", paragraph: this.#paragraph, text: trimmed.slice(0, end).trim() });
+        }
+    }
+    #close(body, events) {
+        if (!this.#lineSent) {
+            // a short paragraph with no sentence end: its whole text is its line
+            events.push({ kind: "line", paragraph: this.#paragraph, text: body.trim().split("\n")[0].trim() });
+        }
+        events.push({ kind: "paragraph", paragraph: this.#paragraph, text: body.trim() });
+        this.#paragraph += 1;
+        this.#lineSent = false;
+    }
+}