@oh-my-pi/pi-tui 18.7.0 → 18.8.0

package/src/native/backend.ts

@@ -14,8 +14,18 @@
  * render while blocked only marks the surface dirty; the next `ack` reconciles
  * once against the last sent state, so every intermediate change coalesces
  * into one frame (`set`s merged, `text append`s joined).
+ *
+ * Blobs. Each image's bytes reach the terminal once per connection. A
+ * terminal with the `blobs` feature is asked first which it already holds:
+ * under `TERN_BLOB_DIR` (Tern's on-disk blob cache, on this machine) every new
+ * blob is written there and then asked about, so its bytes never cross the
+ * pty; otherwise the first pass after (re)connecting asks, so a resumed
+ * session doesn't resend what the terminal kept. Whatever the reply lacks
+ * (or a reply that never comes) is sent inline with `b`. Frames never wait:
+ * the terminal draws an image whose blob arrives after the frame.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import * as logger from "@oh-my-pi/pi-utils/logger";
 import {
 	TSP_DEFAULT_APC_LIMIT,
@@ -40,7 +50,7 @@ import {
 } from "../theme/theme";
 import type { Component, OverlayOptions, RenderScheduler, RenderTimer } from "../tui";
 import { TspDocument } from "./apply";
-import { getNativeBlob } from "./blobs";
+import { getNativeBlob, type NativeBlob } from "./blobs";
 import { node } from "./describe";
 import { encodeTspJson, encodeTspMessage, type TspHello, TspReader, splitTspMessage } from "./encode";
 import type { DescribeContext, NativeChild, NativeNode, NativeSurface, NativeUiEvent } from "./node";
@@ -115,6 +125,44 @@ const RECENT_FRAMES = 64;
 const STALLED_ACK_MS = 5000;
 /** Role of the session's surfaces; a screen page may name its own. */
 const SESSION_ROLE = "omp.session";
+/** A `blobs` query unanswered this long counts its ids as missing: they go inline. */
+const BLOB_REPLY_MS = 3000;
+/** Expired queries kept to pair late replies with their queries, at most. */
+const MAX_BLOB_QUERIES = 16;
+
+/** A `blobs` query awaiting its reply; `timer` is unset once its ids no longer depend on it. */
+interface BlobQuery {
+	readonly ids: readonly string[];
+	timer: RenderTimer | undefined;
+}
+
+/**
+ * Save `blob` in the terminal's blob cache as `<dir>/<id>` (written aside,
+ * then renamed; skipped when present). A failure only means the terminal
+ * won't find it, so the blob goes inline.
+ */
+async function cacheBlob(dir: string, blob: NativeBlob): Promise<void> {
+	const target = path.join(dir, blob.id);
+	const temp = `${target}.tmp${process.pid}`;
+	try {
+		if (await Bun.file(target).exists()) return;
+		// Not `Bun.write`: it would create a missing folder, which only Tern may.
+		await fs.promises.writeFile(temp, blob.bytes);
+		await fs.promises.rename(temp, target);
+	} catch (error) {
+		logger.debug("TSP: could not save a blob to the terminal's cache", { dir, id: blob.id, error: String(error) });
+		await fs.promises.rm(temp, { force: true }).catch(() => {});
+	}
+}
+
+/**
+ * A `b` message's parameters. Tern names a blob by the sha256 of the bytes it
+ * receives and ignores `id`, but Tern 0.5.3 and earlier reject a blob without
+ * it, so it stays until those are gone.
+ */
+function blobParams(blob: NativeBlob): Record<string, string> {
+	return { id: blob.id, mime: blob.mime };
+}
 
 class NativeContext implements DescribeContext {
 	cols: number;
@@ -158,7 +206,8 @@ function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
  * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
  * default APC limit and credits, the terminal's width, the appearance omp
- * already detected, and full motion.
+ * already detected, full motion, and `blobs`, so a resumed session's images
+ * are asked about rather than resent before the reply comes.
  */
 export function assumedTspHello(terminal: Terminal): TspHello {
 	const appearance = terminal.appearance;
@@ -167,6 +216,7 @@ export function assumedTspHello(terminal: Terminal): TspHello {
 		v: TSP_VERSION,
 		term: "tern",
 		kinds: TSP_KINDS,
+		features: ["blobs"],
 		apc: TSP_DEFAULT_APC_LIMIT,
 		credits: TSP_DEFAULT_CREDITS,
 		cols: terminal.columns,
@@ -186,7 +236,6 @@ class Surface {
 	acked = 0;
 	/** Send times of unacknowledged frames, oldest first. */
 	unacked: number[] = [];
-	uploaded = new Set<string>();
 	focus: string | null = null;
 	dirty = false;
 
@@ -256,6 +305,14 @@ export class NativeBackend {
 	#paletteKey: string | undefined;
 	/** Serialized palette last sent, to skip resends of an unchanged theme. */
 	#paletteSent: string | undefined;
+	/** Blobs handled on this connection: asked about in a `blobs` query, or sent (or held by the terminal). */
+	#blobs = new Map<string, "asked" | "sent">();
+	/** `blobs` queries sent, oldest first: the terminal answers each once, in order. */
+	#blobQueries: BlobQuery[] = [];
+	/** The next pass with new blobs asks the terminal which it holds (a fresh connection). */
+	#askHeld = true;
+	/** Bumped when the connection resets or stops, so blob cache writes finishing later are dropped. */
+	#blobEpoch = 0;
 
 	constructor(host: NativeHost, hello: TspHello, options: NativeBackendOptions = {}) {
 		this.#host = host;
@@ -369,6 +426,9 @@ export class NativeBackend {
 		this.#unbindTheme = undefined;
 		this.#useNerdSymbols(false);
 		this.#clearStallTimer();
+		// Replies no longer reach the backend: forget the queries outright.
+		this.#resetBlobs();
+		this.#blobQueries = [];
 	}
 
 	/**
@@ -383,6 +443,7 @@ export class NativeBackend {
 		this.#live = true;
 		this.#useNerdSymbols(true);
 		this.#watchTheme();
+		this.#resetBlobs();
 		const surface = this.#inline;
 		surface.reconciler.detachLive();
 		surface.unacked = [];
@@ -491,7 +552,7 @@ export class NativeBackend {
 			logger.debug("TSP frame", { sf: surface.id, ops: ops.length, rows: surface.reconciler.fallbackCount });
 		}
 		if (ops.length === 0) return;
-		this.#uploadBlobs(surface, ops);
+		this.#uploadBlobs(ops);
 		this.#sendFrame(surface, ops);
 	}
 
@@ -505,6 +566,7 @@ export class NativeBackend {
 		this.#record("in", raw.verb, raw.params, raw.body);
 		const message = this.#reader.feed(sequence);
 		if (message?.verb === "e") this.#handleEvent(message.event);
+		else if (message?.reply.r === "blobs") this.#onBlobsReply(message.reply.have);
 		return true;
 	}
 
@@ -583,25 +645,117 @@ export class NativeBackend {
 		this.#write("f", frame);
 	}
 
-	#uploadBlobs(surface: Surface, ops: readonly TspOp[]): void {
+	/** Deliver the blobs `ops` reference that this connection hasn't handled yet (see the module doc). */
+	#uploadBlobs(ops: readonly TspOp[]): void {
 		const ids = new Set<string>();
 		for (const op of ops) collectBlobs(op, ids);
+		const fresh: NativeBlob[] = [];
 		for (const id of ids) {
-			if (surface.uploaded.has(id)) continue;
+			if (this.#blobs.has(id)) continue;
 			const blob = getNativeBlob(id);
-			if (!blob) {
-				logger.warn("TSP: image references an unregistered blob", { id });
-				continue;
+			if (blob) fresh.push(blob);
+			else logger.warn("TSP: image references an unregistered blob", { id });
+		}
+		if (fresh.length === 0) return;
+		if (!this.#cx.feature("blobs")) {
+			for (const blob of fresh) this.#sendBlob(blob);
+			return;
+		}
+		const dir = Bun.env.TERN_BLOB_DIR;
+		if (dir) {
+			for (const blob of fresh) this.#blobs.set(blob.id, "asked");
+			void this.#cacheBlobs(dir, fresh);
+			return;
+		}
+		if (this.#askHeld) {
+			this.#askHeld = false;
+			this.#askBlobs(fresh.map(blob => blob.id));
+			return;
+		}
+		for (const blob of fresh) this.#sendBlob(blob);
+	}
+
+	/** Write `blobs` to the terminal's cache, then ask about the ones still pending. */
+	async #cacheBlobs(dir: string, blobs: readonly NativeBlob[]): Promise<void> {
+		const epoch = this.#blobEpoch;
+		await Promise.all(blobs.map(blob => cacheBlob(dir, blob)));
+		if (epoch !== this.#blobEpoch) return;
+		const ids = blobs.map(blob => blob.id).filter(id => this.#blobs.get(id) === "asked");
+		if (ids.length > 0) this.#askBlobs(ids);
+	}
+
+	/** Ask the terminal which of `ids` it holds; the reply (or its absence) settles them. */
+	#askBlobs(ids: readonly string[]): void {
+		for (const id of ids) this.#blobs.set(id, "asked");
+		const query: BlobQuery = { ids, timer: undefined };
+		query.timer = this.#scheduler.scheduleRender(() => {
+			query.timer = undefined;
+			logger.warn("TSP: no reply to a blobs query; sending its blobs inline", { ids: ids.length });
+			this.#sendMissing(ids);
+		}, BLOB_REPLY_MS);
+		// Expired queries stay only to pair late replies; a terminal that never answers mustn't grow the list.
+		while (this.#blobQueries.length >= MAX_BLOB_QUERIES && !this.#blobQueries[0]!.timer) this.#blobQueries.shift();
+		this.#blobQueries.push(query);
+		this.#write("q", { q: "blobs", ids });
+	}
+
+	/**
+	 * The reply to the oldest outstanding query. Any `have` id still asked
+	 * about is held by the terminal (whichever query asked); the query's other
+	 * ids go inline.
+	 */
+	#onBlobsReply(have: readonly string[]): void {
+		const query = this.#blobQueries.shift();
+		for (const id of have) {
+			if (this.#blobs.get(id) !== "asked") continue;
+			this.#blobs.set(id, "sent");
+			// The bytes went another way; a recording still carries them so a replay without them shows the image.
+			const blob = this.#recordPath ? getNativeBlob(id) : undefined;
+			if (blob) {
+				const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString(
+					"base64",
+				);
+				this.#record("out", "b", blobParams(blob), body);
 			}
-			surface.uploaded.add(id);
-			const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString("base64");
-			// The full body, so a replay (Tern's `surface-play`) shows the image.
-			this.#record("out", "b", { id, mime: blob.mime }, body);
-			this.#host.terminal.write(encodeTspMessage("b", body, { id, mime: blob.mime }, this.#limit));
+		}
+		if (!query?.timer) return;
+		query.timer.cancel();
+		query.timer = undefined;
+		this.#sendMissing(query.ids);
+	}
+
+	/** Send inline every id of `ids` still waiting on a query. */
+	#sendMissing(ids: readonly string[]): void {
+		for (const id of ids) {
+			const blob = this.#blobs.get(id) === "asked" ? getNativeBlob(id) : undefined;
+			if (blob) this.#sendBlob(blob);
+		}
+	}
+
+	#sendBlob(blob: NativeBlob): void {
+		this.#blobs.set(blob.id, "sent");
+		const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString("base64");
+		// The full body, so a replay (Tern's `surface-play`) shows the image.
+		this.#record("out", "b", blobParams(blob), body);
+		this.#host.terminal.write(encodeTspMessage("b", body, blobParams(blob), this.#limit));
+	}
+
+	/**
+	 * A new connection (resume, or a fresh inline surface after `gone`): the
+	 * terminal is asked again. Outstanding queries stay, without their
+	 * deadlines, only to pair their replies.
+	 */
+	#resetBlobs(): void {
+		this.#blobEpoch++;
+		this.#blobs.clear();
+		this.#askHeld = true;
+		for (const query of this.#blobQueries) {
+			query.timer?.cancel();
+			query.timer = undefined;
 		}
 	}
 
-	#write(verb: "o" | "f" | "t" | "x", body: unknown): void {
+	#write(verb: "o" | "f" | "t" | "x" | "q", body: unknown): void {
 		this.#record("out", verb, undefined, body);
 		this.#host.terminal.write(encodeTspJson(verb, body, undefined, this.#limit));
 	}
@@ -665,6 +819,7 @@ export class NativeBackend {
 			case "gone":
 				if (event.ids.includes(this.#inline.id)) {
 					// Adopt found nothing (evicted, or another pane): start over.
+					this.#resetBlobs();
 					this.#inline = this.#newSurface("inline");
 					if (this.#live) this.#open(this.#inline);
 					this.#host.requestRender();

package/src/native/blobs.ts

@@ -2,8 +2,10 @@
  * Content-addressed binary blobs (images) for `image` nodes.
  *
  * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
- * the native backend uploads each referenced blob once per surface with verb
- * `b` before the frame that first references it.
+ * the native backend delivers each referenced blob once per terminal
+ * connection (asking the terminal first which it holds, or through its blob
+ * cache), else uploads it with verb `b` before the frame that first
+ * references it.
  */
 import type { TspProps } from "@oh-my-pi/pi-wire";
 import { getImageDimensions } from "../terminal-capabilities";

package/src/native/encode.ts

@@ -6,7 +6,9 @@
  * negotiated `apc` limit is split across messages with the same verb, tagged
  * `c=<chunk-id>`, with `m=1` on every chunk but the last; the receiver joins
  * the bodies byte-wise. Chunks split on code-point boundaries, so every chunk
- * is valid UTF-8 on its own and the joined bytes equal the original body.
+ * is valid UTF-8 on its own and the joined bytes equal the original body, and
+ * never where the next chunk would lead with a `key=value;` segment the
+ * receiver would read as a parameter (Tern's `tsp_chunks`).
  */
 import { isRecord } from "@oh-my-pi/pi-utils/type-guards";
 import {
@@ -34,36 +36,58 @@ export type TspParams = Readonly<Record<string, string | number>>;
 
 let nextChunkId = 1;
 
-/** UTF-8 byte length of one UTF-16 code unit sequence starting at `i`, and its unit count. */
-function codePointBytes(text: string, i: number): { bytes: number; units: number } {
-	const c = text.charCodeAt(i);
-	if (c < 0x80) return { bytes: 1, units: 1 };
-	if (c < 0x800) return { bytes: 2, units: 1 };
-	if (c >= 0xd800 && c <= 0xdbff && i + 1 < text.length) {
-		const next = text.charCodeAt(i + 1);
-		if (next >= 0xdc00 && next <= 0xdfff) return { bytes: 4, units: 2 };
+/** Whether `bytes` from `at` leads with a `key=value;` segment, which a receiver reads as one more parameter. */
+function leadsWithParameter(bytes: Uint8Array, at: number): boolean {
+	let i = at;
+	// Key bytes: `[A-Za-z0-9_-]`.
+	for (; i < bytes.length; i++) {
+		const b = bytes[i]!;
+		if (
+			!((b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || b === 0x5f || b === 0x2d)
+		)
+			break;
 	}
-	return { bytes: 3, units: 1 };
+	if (i === at || bytes[i] !== 0x3d) return false;
+	i++;
+	// Value bytes: printable ASCII other than `;`.
+	while (i < bytes.length && bytes[i]! >= 0x21 && bytes[i]! <= 0x7e && bytes[i] !== 0x3b) i++;
+	return bytes[i] === 0x3b;
 }
 
-/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
-export function splitUtf8(body: string, limit: number): string[] {
-	const max = Math.max(4, Math.trunc(limit));
+/**
+ * Where the chunk of `bytes` starting at `start` ends: the safe cut nearest
+ * below `start + limit` (above `start`), else the nearest above it, else the
+ * end. A cut is safe on a UTF-8 character boundary where the rest doesn't
+ * lead with a parameter-shaped segment.
+ */
+function chunkEnd(bytes: Uint8Array, start: number, limit: number): number {
+	const target = start + limit;
+	if (target >= bytes.length) return bytes.length;
+	const safe = (at: number): boolean => (bytes[at]! & 0xc0) !== 0x80 && !leadsWithParameter(bytes, at);
+	for (let at = target; at > start; at--) if (safe(at)) return at;
+	for (let at = target + 1; at < bytes.length; at++) if (safe(at)) return at;
+	return bytes.length;
+}
+
+/**
+ * Chunk bodies for `body` of `byteLength` UTF-8 bytes, cut as Tern's
+ * `tsp_chunks` cuts. Pure ASCII without `;` (every base64 blob) has no
+ * parameter-shaped segment and no multibyte character, so it is cut every
+ * `limit` characters.
+ */
+function chunkBodies(body: string, byteLength: number, limit: number): string[] {
+	const max = Math.max(1, Math.trunc(limit));
 	const pieces: string[] = [];
-	let start = 0;
-	let bytes = 0;
-	let i = 0;
-	while (i < body.length) {
-		const step = codePointBytes(body, i);
-		if (bytes + step.bytes > max) {
-			pieces.push(body.slice(start, i));
-			start = i;
-			bytes = 0;
-		}
-		bytes += step.bytes;
-		i += step.units;
+	if (byteLength === body.length && !body.includes(";")) {
+		for (let at = 0; at < body.length; at += max) pieces.push(body.slice(at, at + max));
+		return pieces;
+	}
+	const bytes = Buffer.from(body, "utf8");
+	for (let start = 0; start < bytes.length;) {
+		const end = chunkEnd(bytes, start, max);
+		pieces.push(bytes.toString("utf8", start, end));
+		start = end;
 	}
-	pieces.push(body.slice(start));
 	return pieces;
 }
 
@@ -79,8 +103,9 @@ function encodeParams(params: TspParams | undefined): string {
 }
 
 /**
- * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
- * Returns the complete byte string to write (all chunks, in order).
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes:
+ * the first chunk carries `params`, every chunk `c=<id>` and all but the last
+ * `m=1`. Returns the complete byte string to write (all chunks, in order).
  */
 export function encodeTspMessage(
 	verb: TspVerb,
@@ -90,13 +115,15 @@ export function encodeTspMessage(
 ): string {
 	const base = encodeParams(params);
 	// Fast path: ASCII-length bound first, exact byte count only near the limit.
-	if (body.length * 3 <= limit || Buffer.byteLength(body, "utf8") <= limit) return frame(verb, base, body);
+	if (body.length * 3 <= limit) return frame(verb, base, body);
+	const byteLength = Buffer.byteLength(body, "utf8");
+	if (byteLength <= limit) return frame(verb, base, body);
 	const chunkId = (nextChunkId++).toString(36);
-	const pieces = splitUtf8(body, limit);
+	const pieces = chunkBodies(body, byteLength, limit);
 	let out = "";
 	for (let i = 0; i < pieces.length; i++) {
 		const more = i < pieces.length - 1 ? ";m=1" : "";
-		out += frame(verb, `${base};c=${chunkId}${more}`, pieces[i]!);
+		out += frame(verb, `${i === 0 ? base : ""};c=${chunkId}${more}`, pieces[i]!);
 	}
 	return out;
 }

package/src/overlays/agent-hub-projection.ts

@@ -23,6 +23,68 @@ function finiteMetric(value: number | undefined): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+/** Message list a fallback metrics read was taken from; unchanged list ⇒ unchanged metrics. */
+interface FallbackReadStamp {
+	messages: readonly unknown[];
+	length: number;
+	last: unknown;
+	/** Usage and block count of the last message, which a streaming turn mutates in place. */
+	lastShape: string;
+	/** Session model, whose context window the context gauge reports. */
+	model: unknown;
+	contextWindow: number | null | undefined;
+}
+
+/** Stamp of each cached fallback read, keyed by the cache entry so it cannot outlive that read. */
+const fallbackReadStamps = new WeakMap<object, FallbackReadStamp>();
+
+function lastMessageShape(last: unknown): string {
+	if (!last || typeof last !== "object") return "";
+	const { usage, content } = last as {
+		usage?: { input?: number; output?: number; cacheWrite?: number; cost?: { total?: number } };
+		content?: unknown;
+	};
+	const blocks = Array.isArray(content) ? content.length : -1;
+	return `${usage?.input}:${usage?.output}:${usage?.cacheWrite}:${usage?.cost?.total}:${blocks}`;
+}
+
+function fallbackReadStamp(session: NonNullable<AgentRecordLike["session"]>): FallbackReadStamp | undefined {
+	try {
+		const messages = session.agent?.state?.messages;
+		if (!Array.isArray(messages)) return undefined;
+		const last = messages[messages.length - 1];
+		return {
+			messages,
+			length: messages.length,
+			last,
+			lastShape: lastMessageShape(last),
+			model: session.model,
+			contextWindow: session.model?.contextWindow,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Whether a cached fallback read still matches the session's message list
+ * (append, compaction, rewrite, streaming tail) and model (context window).
+ */
+function fallbackReadCurrent(entry: object, session: NonNullable<AgentRecordLike["session"]>): boolean {
+	const stamp = fallbackReadStamps.get(entry);
+	if (!stamp) return false;
+	const current = fallbackReadStamp(session);
+	return (
+		current !== undefined &&
+		current.messages === stamp.messages &&
+		current.length === stamp.length &&
+		current.last === stamp.last &&
+		current.lastShape === stamp.lastShape &&
+		current.model === stamp.model &&
+		current.contextWindow === stamp.contextWindow
+	);
+}
+
 /** Exact observer usage for one roster entry. */
 export function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined {
 	const progress = observed?.progress;
@@ -163,8 +225,14 @@ export function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
 		const fallbackSession = args.fallbackStatsSession(ref, observed);
 		if (fallbackSession) {
 			hasFallbackLiveSessions = true;
-			if (args.refreshFallback || !args.sessionMetrics.has(fallbackSession)) {
-				args.sessionMetrics.set(fallbackSession, { metrics: readSessionMetrics(fallbackSession) });
+			const cached = args.sessionMetrics.get(fallbackSession);
+			// A refresh rescans every assistant message (plus the host's stats);
+			// skip it while the message list is provably the one already read.
+			if (!cached || (args.refreshFallback && !fallbackReadCurrent(cached, fallbackSession))) {
+				const stamp = fallbackReadStamp(fallbackSession);
+				const entry = { metrics: readSessionMetrics(fallbackSession) };
+				if (stamp) fallbackReadStamps.set(entry, stamp);
+				args.sessionMetrics.set(fallbackSession, entry);
 			}
 		}
 		const metrics = args.metricsFor(ref, observed);

package/src/overlays/agent-hub.ts

@@ -1589,7 +1589,8 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		for (const ref of rosterRows) this.#statusCounts[ref.status]++;
 		this.#refreshAggregate();
 		this.#refreshActivityData(rosterRows);
-		this.#refreshActivityRows();
+		// The 2,000-row activity query only feeds the Activity tab; switching to it refreshes.
+		if (this.#section === "activity") this.#refreshActivityRows();
 	}
 
 	#refreshActivityData(refs: readonly TRecord[]): void {
@@ -1620,7 +1621,7 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		void Promise.all(pending)
 			.then(() => {
 				if (this.#disposed || generation !== this.#activitySyncGeneration) return;
-				this.#refreshActivityRows();
+				if (this.#section === "activity") this.#refreshActivityRows();
 				this.#requestRender();
 			})
 			.catch(() => {