@vzlentin/harness 0.2.3 → 0.3.0

package/dist/view-change.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The change of a watched conversation view that a watch line carries, and its two ends: the host makes it from the
+ * chord ops of a commit, and a client applies it, so the client needs no chord. It imports only types, so the Pi
+ * extension can load it.
+ *
+ * The entries of a change are the entries from one index to the end. This is correct because no op moves the entries
+ * before the index where it starts: a splice starts at its index, a change in an entry at that entry, and a reorder or
+ * a new array at the first entry.
+ */
+import type { Op } from "@earendil-works/chord/delta";
+import type { ConversationRecord, ConversationView, EntryRecord, JsonObject } from "@earendil-works/pi-durable";
+/**
+ * The parts of a watched view that changed, as whole values: the entries from index `from` on, the documents that
+ * changed by kind (`null` for a removed document), and the conversation record. A part that did not change is absent.
+ */
+export type ViewParts = {
+    readonly entries?: {
+        readonly from: number;
+        readonly items: readonly EntryRecord[];
+    };
+    readonly docs?: Readonly<Record<string, JsonObject | null>>;
+    readonly conversation?: ConversationRecord;
+};
+/**
+ * What one commit changed in a watched view, so a client keeps the view without chord: some parts, or the whole view,
+ * as after a watch that fell behind.
+ */
+export type ViewChange = ViewParts | {
+    readonly view: ConversationView;
+};
+/**
+ * What `ops` changed in a watched view, as whole values of `view`, the view after them: the entries from the first one
+ * that an op reached, each document that an op reached, and the conversation record. An op on the root, or on a part
+ * that this does not know, gives the whole view.
+ */
+export declare function viewChange(view: ConversationView, ops: readonly Op[]): ViewChange;
+/** `view` after `change`. A client of a watch keeps its view up to date with it. */
+export declare function applyChange(view: ConversationView, change: ViewChange): ConversationView;

package/dist/view-change.js

@@ -0,0 +1,55 @@
+/**
+ * What `ops` changed in a watched view, as whole values of `view`, the view after them: the entries from the first one
+ * that an op reached, each document that an op reached, and the conversation record. An op on the root, or on a part
+ * that this does not know, gives the whole view.
+ */
+export function viewChange(view, ops) {
+    let from;
+    const kinds = new Set();
+    let conversation = false;
+    for (const op of ops) {
+        if (op[0] === "r")
+            return { view };
+        const [part, next] = op[1];
+        if (part === "entries") {
+            const index = next !== undefined ? Number(next) : op[0] === "p" ? op[2] : 0;
+            from = Math.min(from ?? index, index);
+        }
+        else if (part === "docs" && next !== undefined) {
+            kinds.add(String(next));
+        }
+        else if (part === "conversation") {
+            conversation = true;
+        }
+        else {
+            return { view };
+        }
+    }
+    const parts = {};
+    if (from !== undefined)
+        parts.entries = { from, items: view.entries.slice(from) };
+    if (kinds.size > 0) {
+        parts.docs = Object.fromEntries([...kinds].map((kind) => [kind, view.docs[kind] ?? null]));
+    }
+    if (conversation)
+        parts.conversation = view.conversation;
+    return parts;
+}
+/** `view` after `change`. A client of a watch keeps its view up to date with it. */
+export function applyChange(view, change) {
+    if ("view" in change)
+        return change.view;
+    const { entries, docs = {}, conversation } = change;
+    const changedDocs = { ...view.docs };
+    for (const [kind, doc] of Object.entries(docs)) {
+        if (doc === null)
+            delete changedDocs[kind];
+        else
+            changedDocs[kind] = doc;
+    }
+    return {
+        conversation: conversation ?? view.conversation,
+        entries: entries === undefined ? view.entries : [...view.entries.slice(0, entries.from), ...entries.items],
+        docs: changedDocs,
+    };
+}

package/dist/view-state.d.ts

@@ -1,19 +1,35 @@
 /**
- * What the viewer reads from the documents of a durable conversation view: its live state, its inbox and the texts of
- * its user messages.
+ * What the Pi extension reads from a durable conversation view: its live state, its inbox, its usage and
+ * the texts of its user messages. It imports only types, so the Pi extension can load it.
  */
 import type { JsonRepresentation } from "@earendil-works/chord";
-import type { UserMessage } from "@earendil-works/pi-ai";
-import { type ConversationDocToken, type ConversationView, type InboxState, type JsonObject, type LiveState } from "@earendil-works/pi-durable";
-/** The built-in document of `token` in `view`, if the conversation has it. */
-export declare function docOf<T extends JsonObject>(view: ConversationView, token: ConversationDocToken<T>): T | undefined;
+import type { Usage, UserMessage } from "@earendil-works/pi-ai";
+import type { ConversationView, InboxState, LiveState, UsageState } from "@earendil-works/pi-durable";
 export declare function liveOf(view: ConversationView): LiveState;
 export declare function inboxOf(view: ConversationView): InboxState;
+export declare function usageOf(view: ConversationView): UsageState | undefined;
+/** The tokens and the cost of a conversation. */
+export type UsageTotals = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+};
+/** The sums of the usage of the model requests and of the tool results of the conversation, as Pi's footer counts. */
+export declare function usageTotals(view: ConversationView): UsageTotals;
+/**
+ * The usage of the last answer of the active transcript, which tells how full the context is. An aborted answer and an
+ * answer that failed do not count.
+ */
+export declare function lastAnswerUsage(view: ConversationView): Usage | undefined;
 export declare function userText(content: JsonRepresentation<UserMessage["content"]>): string;
 /** The queued steers and follow-ups, in inbox order. */
 export declare function queued(inbox: InboxState): {
     mode: "steer" | "followUp";
     text: string;
 }[];
+/** The texts of the queued messages that an abort withdraws, steers first, as they go back to the editor. */
+export declare function withdrawnTexts(inbox: InboxState): string[];
 /** What the conversation does now, as Pi's working indicator says it; empty when it does nothing. */
 export declare function statusText(live: LiveState): string;

package/dist/view-state.js

@@ -1,14 +1,44 @@
-import { InboxDoc, LiveDoc, } from "@earendil-works/pi-durable";
-/** The built-in document of `token` in `view`, if the conversation has it. */
-export function docOf(view, token) {
-    // SAFETY: pi-durable keeps each built-in conversation document in `docs` under the kind of its token.
-    return view.docs[token.definition.kind];
+/** The built-in document of the kind `kind` in `view`, if the conversation has it. */
+function docOf(view, kind) {
+    // SAFETY: pi-durable keeps each built-in conversation document in `docs` under its kind: `pi.live` holds a
+    // `LiveState`, `pi.inbox` an `InboxState` and `pi.usage` a `UsageState`. Each caller passes the kind of its type.
+    return view.docs[kind];
 }
 export function liveOf(view) {
-    return docOf(view, LiveDoc) ?? {};
+    return docOf(view, "pi.live") ?? {};
 }
 export function inboxOf(view) {
-    return docOf(view, InboxDoc) ?? { items: [] };
+    return docOf(view, "pi.inbox") ?? { items: [] };
+}
+export function usageOf(view) {
+    return docOf(view, "pi.usage");
+}
+/** The sums of the usage of the model requests and of the tool results of the conversation, as Pi's footer counts. */
+export function usageTotals(view) {
+    const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    const usage = usageOf(view);
+    for (const item of [...Object.values(usage?.models ?? {}), ...Object.values(usage?.tools ?? {})]) {
+        totals.input += item.input;
+        totals.output += item.output;
+        totals.cacheRead += item.cacheRead;
+        totals.cacheWrite += item.cacheWrite;
+        totals.cost += item.cost.total;
+    }
+    return totals;
+}
+/**
+ * The usage of the last answer of the active transcript, which tells how full the context is. An aborted answer and an
+ * answer that failed do not count.
+ */
+export function lastAnswerUsage(view) {
+    for (const entry of view.entries.toReversed()) {
+        const message = entry.model?.[0];
+        if (entry.kind !== "pi.assistant" || message?.role !== "assistant")
+            continue;
+        if (message.stopReason !== "aborted" && message.stopReason !== "error")
+            return message.usage;
+    }
+    return undefined;
 }
 export function userText(content) {
     if (!Array.isArray(content))
@@ -22,6 +52,14 @@ export function userText(content) {
 export function queued(inbox) {
     return inbox.items.flatMap((item) => item.mode === "write" ? [] : [{ mode: item.mode, text: userText(item.content) }]);
 }
+/** The texts of the queued messages that an abort withdraws, steers first, as they go back to the editor. */
+export function withdrawnTexts(inbox) {
+    const inputs = queued(inbox);
+    return [
+        ...inputs.filter((input) => input.mode === "steer"),
+        ...inputs.filter((input) => input.mode === "followUp"),
+    ].map((input) => input.text);
+}
 /** What the conversation does now, as Pi's working indicator says it; empty when it does nothing. */
 export function statusText(live) {
     const generation = live.generation;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vzlentin/harness",
-	"version": "0.2.3",
+	"version": "0.3.0",
 	"description": "A durable agent harness on Pi, starting with observable, persistent subagents",
 	"repository": {
 		"type": "git",
@@ -35,6 +35,7 @@
 	"dependencies": {
 		"@earendil-works/chord": "1.3.0",
 		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-codemode": "1.3.0",
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-durable": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",

package/pi/attachment.ts

@@ -0,0 +1,296 @@
+/**
+ * The mirror of one Pi session: the frame of its entry in Pi's chat, which holds the transcript, the status above the
+ * editor, and an editor whose interrupt and follow-up keys act on the agent while it works. The connection to the host
+ * is the `Mirror`, and the model and thinking level of the session are the `ModelSync`.
+ */
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	KeybindingsManager,
+	Theme,
+	ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import * as coding from "@earendil-works/pi-coding-agent";
+import type { ConversationView } from "@earendil-works/pi-durable";
+import type { Component, EditorTheme, TUI } from "@earendil-works/pi-tui";
+import * as tui from "@earendil-works/pi-tui";
+import { type AgentReporter, agentReporter } from "../dist/herdr.js";
+import { Mirror, type MirrorStatus, type MirrorTarget, targetTitle } from "../dist/mirror.js";
+import { type ChildInfo, childLabel, childTitle, errorMessage } from "../dist/protocol.js";
+import { inboxOf, liveOf, queued, statusText } from "../dist/view-state.js";
+import { ChatView } from "./chat.ts";
+import { ModelSync } from "./model-sync.ts";
+import { usageLine } from "./usage-line.ts";
+
+/** The key of the status widget above the editor. */
+const WIDGET = "harness-mirror";
+
+export class Attachment {
+	readonly entryId: string;
+	readonly models: ModelSync;
+	// After a session switch, `#pi` and `#ctx` are stale and throw, so only code that checks `#closed` uses them. The
+	// components that Pi draws use `#theme` instead.
+	readonly #pi: ExtensionAPI;
+	readonly #ctx: ExtensionContext;
+	#theme: Theme;
+	readonly #frame: tui.Container;
+	readonly #status = new StatusArea();
+	readonly #mirror: Mirror;
+	#ui: TUI | undefined;
+	#chat: ChatView | undefined;
+	/** The state of the agent for Herdr, made when the agent is first known. */
+	#reporter: AgentReporter | undefined;
+	#expanded = false;
+	#closed = false;
+
+	constructor(pi: ExtensionAPI, ctx: ExtensionContext, entryId: string, target: MirrorTarget, frame: tui.Container) {
+		this.entryId = entryId;
+		this.#pi = pi;
+		this.#ctx = ctx;
+		this.#theme = ctx.ui.theme;
+		this.#frame = frame;
+		this.#frame.clear();
+		this.#frame.addChild(this.#line("muted", () => `Connecting to the ${targetTitle(target)}...`));
+		// Pi calls the factory at once, which gives the TUI that the tool cards need.
+		ctx.ui.setWidget(
+			WIDGET,
+			(ui, theme) => {
+				this.#ui = ui;
+				this.#theme = theme;
+
+				return this.#status;
+			},
+			{ placement: "aboveEditor" },
+		);
+		ctx.ui.setEditorComponent((ui, theme, keybindings) => new MirrorEditor(ui, theme, keybindings, this));
+		this.#mirror = new Mirror(target, (previous) => this.#update(previous));
+		this.models = new ModelSync(pi, ctx, this.#mirror, (cause) => this.#notify(cause));
+	}
+
+	get busy(): boolean {
+		return this.#mirror.busy;
+	}
+
+	/**
+	 * Sends `text` to the agent: a new turn when it is idle, else a steer, or a follow-up with `followUp`. A text that
+	 * does not reach the agent goes back to the editor, after the text there, so it is not lost.
+	 */
+	send(text: string, followUp: boolean): void {
+		this.#mirror.send(text, followUp).catch((cause: unknown) => {
+			if (this.#closed) return;
+			const editor = this.#ctx.ui.getEditorText();
+			this.#ctx.ui.setEditorText([editor, text].filter((part) => part.trim() !== "").join("\n\n"));
+			this.#ctx.ui.notify(`harness: not sent: ${errorMessage(cause)}`, "error");
+		});
+	}
+
+	/** Aborts the agent's turn. The queued messages that the host withdraws go back to `editor`, steers first. */
+	abort(editor: Pick<tui.Editor, "getText" | "setText">): void {
+		this.#mirror.abort().then(
+			(texts) => {
+				if (this.#closed) return;
+				const text = [...texts, editor.getText()].filter((part) => part.trim() !== "").join("\n\n");
+
+				if (text !== editor.getText()) editor.setText(text);
+			},
+			(cause: unknown) => this.#notify(cause),
+		);
+	}
+
+	/** Takes the theme and the expanded state of tool output that Pi gives when it draws the entry again. */
+	restyle(theme: Theme, expanded: boolean): void {
+		this.#theme = theme;
+		this.#expanded = expanded;
+		this.#chat?.setExpanded(expanded);
+		this.showThinkingSetting();
+	}
+
+	/** Shows or hides the thinking of the answers, as Pi's `hideThinkingBlock` setting says. */
+	showThinkingSetting(): void {
+		if (!this.#closed) this.#chat?.setHideThinking(this.#pi.getSettings().hideThinkingBlock ?? false);
+	}
+
+	/** Closes the connection and gives Pi back its editor. The agent keeps running in the host. */
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.models.close();
+		this.#mirror.close();
+		this.#chat?.stopTimers();
+		this.#status.dispose();
+		this.#ctx.ui.setWidget(WIDGET, undefined);
+		this.#ctx.ui.setEditorComponent(undefined);
+		void this.#reporter?.release();
+	}
+
+	/** Shows each change of the mirror, whose status was `previous` before it. */
+	#update(previous: MirrorStatus): void {
+		const ui = this.#ui;
+
+		if (ui === undefined || this.#closed) return;
+		const { status, view, child } = this.#mirror;
+
+		if (view !== undefined && child !== undefined) this.#showTranscript(ui, view, child, previous);
+		this.#showStatus(ui, view, child);
+
+		if (status.kind === "failed" && previous.kind !== "failed") this.#showFailure(status.reason);
+		this.#reporter?.report(this.#mirror.busy);
+
+		if (child !== undefined) this.#followAgent(child);
+		ui.requestRender();
+	}
+
+	/**
+	 * Shows the transcript under its header, and makes the Herdr reporter at the first connection. It applies `view` only
+	 * on an open connection.
+	 */
+	#showTranscript(ui: TUI, view: ConversationView, child: ChildInfo, previous: MirrorStatus): void {
+		const chat = this.#chat ?? this.#startTranscript(ui, child);
+
+		if (this.#mirror.status.kind === "open") chat.apply(view);
+		// A running bash card keeps its timer until it gets a final result, and no connection gives one now.
+		else if (previous.kind === "open") chat.stopTimers();
+	}
+
+	#startTranscript(ui: TUI, first: ChildInfo): ChatView {
+		const chat = new ChatView(ui, first.cwd, (name, text) => this.#theme.fg(name, text));
+		this.#chat = chat;
+		chat.setExpanded(this.#expanded);
+		this.showThinkingSetting();
+		this.#frame.clear();
+		this.#frame.addChild(this.#line("muted", () => this.#header(this.#mirror.child ?? first)));
+		this.#frame.addChild(chat.transcript);
+		this.#reporter = agentReporter(process.env, childLabel(first), this.#mirror.target);
+
+		return chat;
+	}
+
+	/** Shows above the editor what the agent does, its queued messages and its usage line. */
+	#showStatus(ui: TUI, view: ConversationView | undefined, child: ChildInfo | undefined): void {
+		const { status, busy } = this.#mirror;
+		const lines: string[] = [];
+
+		if (view !== undefined && status.kind === "open") {
+			for (const { mode, text } of queued(inboxOf(view))) {
+				lines.push(this.#theme.fg("dim", `${mode === "steer" ? "Steer" : "Follow-up"}: ${text.split("\n")[0] ?? ""}`));
+			}
+		}
+
+		if (view !== undefined && child !== undefined) {
+			lines.push(usageLine(this.#theme, this.#ctx.modelRegistry, child, view));
+		}
+
+		const working =
+			status.kind === "reconnecting"
+				? "Connecting again to the harness host..."
+				: busy && view !== undefined
+					? statusText(liveOf(view)) || "Working..."
+					: "";
+
+		this.#status.show(ui, this.#theme, working, lines);
+	}
+
+	#showFailure(reason: string): void {
+		// Without a transcript, the error takes the place of the connecting line.
+		if (this.#chat === undefined) this.#frame.clear();
+		this.#frame.addChild(this.#line("error", () => reason));
+		this.#ctx.ui.notify(`harness: ${reason}`, "error");
+	}
+
+	/** Gives Pi the agent's title, and on an open connection its model and thinking level. */
+	#followAgent(child: ChildInfo): void {
+		if (this.#mirror.status.kind === "open") this.models.fromAgent(child);
+		const title = childTitle(child);
+
+		if (this.#pi.getSessionName() !== title) this.#pi.setSessionName(title);
+	}
+
+	#notify(cause: unknown): void {
+		if (!this.#closed) this.#ctx.ui.notify(`harness: ${errorMessage(cause)}`, "error");
+	}
+
+	#header(child: ChildInfo): string {
+		const theme = this.#theme;
+
+		return [theme.bold(theme.fg("accent", "harness")), theme.fg("text", childTitle(child)), child.cwd].join(" │ ");
+	}
+
+	/** One line in the theme color `name`, colored at each render so that it follows a change of theme. */
+	#line(name: ThemeColor, text: () => string): Component {
+		return {
+			render: (width) => [tui.truncateToWidth(` ${this.#theme.fg(name, text())}`, width)],
+			invalidate: () => {},
+		};
+	}
+}
+
+/**
+ * The editor of a mirror session. While the agent works, the interrupt key (Esc) aborts its turn and the follow-up key
+ * (Alt+Enter) queues the text as a follow-up. Pi's editor handles every other key. After the key that hides thinking
+ * (Ctrl+T), which Pi applies only to its own messages, the transcript of the agent follows the setting. After the key
+ * that cycles the thinking level (Shift+Tab), the agent gets the level of Pi.
+ */
+class MirrorEditor extends coding.CustomEditor {
+	readonly #keys: KeybindingsManager;
+	readonly #attachment: Attachment;
+
+	constructor(ui: TUI, theme: EditorTheme, keys: KeybindingsManager, attachment: Attachment) {
+		super(ui, theme, keys);
+		this.#keys = keys;
+		this.#attachment = attachment;
+	}
+
+	handleInput(data: string): void {
+		if (this.#attachment.busy && this.#keys.matches(data, "app.interrupt") && !this.isShowingAutocomplete()) {
+			this.#attachment.abort(this);
+
+			return;
+		}
+
+		if (this.#attachment.busy && this.#keys.matches(data, "app.message.followUp")) {
+			const text = this.getExpandedText().trim();
+
+			if (text !== "") {
+				this.addToHistory(text);
+				this.setText("");
+				this.#attachment.send(text, true);
+			}
+
+			return;
+		}
+
+		super.handleInput(data);
+
+		if (this.#keys.matches(data, "app.thinking.toggle")) this.#attachment.showThinkingSetting();
+
+		if (this.#keys.matches(data, "app.thinking.cycle")) this.#attachment.models.piCycled();
+	}
+}
+
+/** The status of the agent above the editor: Pi's working indicator while it works, then some lines. */
+class StatusArea extends tui.Container {
+	#loader: tui.Loader | undefined;
+
+	/** Shows `status` with a spinner, or nothing when it is empty, then each of `lines`, cut to the width. */
+	show(ui: TUI, theme: Theme, status: string, lines: readonly string[]): void {
+		if (status === "") {
+			this.dispose();
+		} else if (this.#loader === undefined) {
+			const spinner = (text: string) => theme.fg("accent", text);
+			this.#loader = new tui.Loader(ui, spinner, (text) => theme.fg("muted", text), status);
+		} else {
+			this.#loader.setMessage(status);
+		}
+
+		this.clear();
+
+		if (this.#loader !== undefined) this.addChild(this.#loader);
+
+		for (const line of lines) this.addChild(new tui.TruncatedText(line, 1, 0));
+	}
+
+	dispose(): void {
+		this.#loader?.stop();
+		this.#loader = undefined;
+	}
+}