@vzlentin/harness 0.2.3 → 0.3.1

package/pi/mirror.ts

@@ -0,0 +1,218 @@
+/**
+ * Mirror sessions: a Pi session that shows a child or the agent of a harness project in Pi's own chat, and sends what
+ * the user types to it. The agent runs in the host of the project; the session keeps only its target, in one custom
+ * entry. `/harness [project]` opens one in a new session, and `pi --harness <project> [--harness-child <handle> |
+ * --harness-conversation <id>]` in the session that Pi starts with.
+ */
+
+import { homedir } from "node:os";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import * as tui from "@earendil-works/pi-tui";
+import { isMirrorTarget, MIRROR_ENTRY, type MirrorTarget, PI_FLAGS } from "../dist/mirror.js";
+import { checkProject, MAIN_PROJECT, projectDir, readProjects, resolveProject } from "../dist/projects.js";
+import { AGENT_HANDLE, errorMessage } from "../dist/protocol.js";
+import { Attachment } from "./attachment.ts";
+
+/** The mirror entry of a session: its ID and its target. */
+type MirrorEntry = { readonly id: string; readonly target: MirrorTarget };
+
+/** Registers `/harness`, `--harness` and the handlers that turn a session with a mirror entry into a mirror session. */
+export function registerMirror(pi: ExtensionAPI): void {
+	// The frame of each mirror entry in Pi's chat. Pi can draw the entry before or after `session_start`.
+	const frames = new Map<string, tui.Container>();
+	let attached: Attachment | undefined;
+
+	const frameOf = (entryId: string): tui.Container => {
+		const frame = frames.get(entryId) ?? new tui.Container();
+		frames.set(entryId, frame);
+
+		return frame;
+	};
+
+	pi.registerFlag(PI_FLAGS.project, {
+		type: "string",
+		description: "Show the agent of this harness project (main or a project name) in the new session",
+	});
+
+	pi.registerFlag(PI_FLAGS.child, {
+		type: "string",
+		description: "Show this subagent of the harness project in the new session, in place of the project agent",
+	});
+
+	pi.registerFlag(PI_FLAGS.conversation, {
+		type: "string",
+		description:
+			"Show this conversation of the children library of the harness project in the new session, in place of the project agent",
+	});
+
+	pi.registerEntryRenderer(MIRROR_ENTRY, (entry, options, theme) => {
+		if (attached?.entryId === entry.id) attached.restyle(theme, options.expanded);
+
+		return frameOf(entry.id);
+	});
+
+	pi.registerCommand("harness", {
+		description: "Show the agent of a harness project in a new session: /harness [project]",
+		getArgumentCompletions: projectItems,
+		handler: async (args, ctx) => {
+			let project: string | undefined;
+
+			try {
+				project = args.trim() === "" ? await pickProject(ctx) : checkProject(args.trim());
+			} catch (error) {
+				ctx.ui.notify(`harness: ${errorMessage(error)}`, "error");
+
+				return;
+			}
+
+			if (project === undefined) return;
+			const target: MirrorTarget = { project, handle: AGENT_HANDLE };
+			await ctx.newSession({
+				setup: async (sessionManager) => {
+					sessionManager.appendCustomEntry(MIRROR_ENTRY, target);
+				},
+			});
+		},
+	});
+
+	pi.on("session_start", (event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		const branch = ctx.sessionManager.getBranch();
+
+		// Pi draws only the entries of this branch from now on. A /reload keeps the session, and its frames.
+		for (const id of frames.keys()) {
+			if (!branch.some((entry) => entry.id === id)) frames.delete(id);
+		}
+
+		const entry = mirrorEntry(branch) ?? (event.reason === "startup" ? flagEntry(pi, ctx) : undefined);
+
+		if (entry !== undefined) attached = new Attachment(pi, ctx, entry.id, entry.target, frameOf(entry.id));
+	});
+
+	pi.on("session_shutdown", () => {
+		attached?.close();
+		attached = undefined;
+	});
+
+	// The agent of the host answers in a mirror session, so the input goes there and not to Pi's own agent.
+	pi.on("input", (event, ctx) => {
+		if (attached === undefined) return undefined;
+
+		if (event.images !== undefined && event.images.length > 0) {
+			ctx.ui.notify("harness: the images are not sent; the agent gets only the text", "warning");
+		}
+
+		attached.send(event.text, false);
+
+		return { action: "handled" };
+	});
+
+	// A restored model is the one of the Pi session, not a choice of the user.
+	pi.on("model_select", (event) => {
+		if (event.source !== "restore") attached?.models.piSelected(event.model.provider, event.model.id);
+	});
+}
+
+/** The newest mirror entry of `entries` with a valid target. */
+function mirrorEntry(entries: readonly SessionEntry[]): MirrorEntry | undefined {
+	for (const entry of entries.toReversed()) {
+		if (entry.type === "custom" && entry.customType === MIRROR_ENTRY && isMirrorTarget(entry.data)) {
+			return { id: entry.id, target: entry.data };
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * The mirror entry for `--harness <project>`, `--harness-child <handle>` and `--harness-conversation <id>`, written in
+ * the session that Pi starts with. Without a project, it is the project of `HARNESS_PROJECT` and Pi's working
+ * directory; without a child or a conversation, the project agent. It refuses both a child and a conversation, and a
+ * session with messages, such as one of `--continue`, because Pi's own agent answered there.
+ */
+function flagEntry(pi: ExtensionAPI, ctx: ExtensionContext): MirrorEntry | undefined {
+	const project = stringFlag(pi, PI_FLAGS.project);
+	const child = stringFlag(pi, PI_FLAGS.child);
+	const conversation = stringFlag(pi, PI_FLAGS.conversation);
+
+	if (project === undefined && child === undefined && conversation === undefined) return undefined;
+
+	if (child && conversation) {
+		ctx.ui.notify("harness: use --harness-child or --harness-conversation, not both", "error");
+
+		return undefined;
+	}
+
+	if (ctx.sessionManager.getBranch().some((entry) => entry.type === "message")) {
+		ctx.ui.notify("harness: --harness needs a new session, not one with messages", "error");
+
+		return undefined;
+	}
+
+	let target: MirrorTarget;
+
+	try {
+		const name = project ? checkProject(project) : resolveProject(process.env, ctx.cwd);
+		target = conversation ? { project: name, conversation } : { project: name, handle: child || AGENT_HANDLE };
+	} catch (error) {
+		ctx.ui.notify(`harness: ${errorMessage(error)}`, "error");
+
+		return undefined;
+	}
+
+	// `appendEntry` gives no entry ID, so the entry comes back from the branch.
+	pi.appendEntry(MIRROR_ENTRY, target);
+
+	return mirrorEntry(ctx.sessionManager.getBranch());
+}
+
+/** The value of the string flag `name`, or undefined when it is not given. */
+function stringFlag(pi: ExtensionAPI, name: string): string | undefined {
+	const flag = pi.getFlag(name);
+
+	return flag === undefined || flag === true || flag === false ? undefined : flag;
+}
+
+/**
+ * The project that the user selects for `/harness` without a project: the project of Pi's working directory first,
+ * then the other projects and `main`. It is undefined when the user cancels.
+ */
+async function pickProject(ctx: ExtensionCommandContext): Promise<string | undefined> {
+	const projects = readProjects();
+	const current = resolveProject(process.env, ctx.cwd, projects);
+	const names = [current, ...[...Object.keys(projects), MAIN_PROJECT].filter((name) => name !== current)];
+
+	if (names.length === 1) return current;
+	const labels = names.map((name) => `${name}  ${tildePath(projectDir(name, projects))}`);
+	const label = await ctx.ui.select("Harness project", labels);
+
+	return label === undefined ? undefined : names[labels.indexOf(label)];
+}
+
+/** `path` with the home directory as `~`. */
+function tildePath(path: string): string {
+	const home = homedir();
+
+	return home !== "" && (path === home || path.startsWith(`${home}/`)) ? `~${path.slice(home.length)}` : path;
+}
+
+/** The projects whose names start with `prefix`, for the argument of `/harness`. */
+function projectItems(prefix: string): AutocompleteItem[] | null {
+	let names: string[];
+
+	try {
+		names = [...Object.keys(readProjects()), MAIN_PROJECT];
+	} catch {
+		return null;
+	}
+
+	const items = names.flatMap((name) => (name.startsWith(prefix) ? [{ value: name, label: name }] : []));
+
+	return items.length > 0 ? items : null;
+}

package/pi/model-sync.ts

@@ -0,0 +1,102 @@
+/**
+ * The model and the thinking level of a mirror session. The agent in the host is the truth: the Pi session shows the
+ * agent's model and level, so Pi's footer and `/model` show them, and a change that the user makes in Pi is a request
+ * to the host. When the host refuses it, Pi goes back to the agent's model and level.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Mirror, MirrorConfigure } from "../dist/mirror.js";
+import type { ChildInfo } from "../dist/protocol.js";
+
+/** What the sync uses of Pi's extension API. */
+export type PiModels = Pick<ExtensionAPI, "setModel" | "getThinkingLevel" | "setThinkingLevel">;
+
+/** What the sync uses of the context of the Pi session. */
+export type PiSession = Pick<ExtensionContext, "model"> & {
+	readonly modelRegistry: Pick<ExtensionContext["modelRegistry"], "find">;
+};
+
+/** What the sync uses of the mirror: the agent, and the requests that change it. */
+export type MirroredAgent = Pick<Mirror, "child" | "configure">;
+
+export class ModelSync {
+	// After a session switch, `#pi` and `#ctx` are stale and throw, so nothing uses them after `close()`.
+	readonly #pi: PiModels;
+	readonly #ctx: PiSession;
+	readonly #mirror: MirroredAgent;
+	readonly #notify: (cause: unknown) => void;
+	/** True while Pi sets the agent's model: `setModel` is async, and the agent changes often while it works. */
+	#settingModel = false;
+	#closed = false;
+
+	constructor(pi: PiModels, ctx: PiSession, mirror: MirroredAgent, notify: (cause: unknown) => void) {
+		this.#pi = pi;
+		this.#ctx = ctx;
+		this.#mirror = mirror;
+		this.#notify = notify;
+	}
+
+	/** Gives the Pi session the model and the thinking level of `child`, the agent as the host gives it. */
+	fromAgent(child: ChildInfo): void {
+		if (this.#closed) return;
+		const model = this.#ctx.modelRegistry.find(child.provider, child.model);
+
+		if (model !== undefined && !this.#piHasModel(child) && !this.#settingModel) {
+			this.#settingModel = true;
+			// Pi sets its own thinking level when it takes a model, so the agent's level follows once Pi has the model.
+			void this.#pi.setModel(model).finally(() => {
+				this.#settingModel = false;
+				const current = this.#mirror.child;
+
+				if (current !== undefined) this.#thinkingFromAgent(current);
+			});
+		}
+
+		this.#thinkingFromAgent(child);
+	}
+
+	/** Asks the host for the model that the user selected in Pi. */
+	piSelected(provider: string, model: string): void {
+		const child = this.#mirror.child;
+
+		if (child === undefined || (child.provider === provider && child.model === model)) return;
+		this.#configure({ provider, model });
+	}
+
+	/**
+	 * Asks the host for the thinking level that the user cycled to in Pi, once Pi has the agent's model. Pi also changes
+	 * its level when it takes a model, so only the cycle key calls this, not each change of Pi's level.
+	 */
+	piCycled(): void {
+		const child = this.#mirror.child;
+
+		if (this.#closed || child === undefined || !this.#piHasModel(child)) return;
+		const thinking = this.#pi.getThinkingLevel();
+
+		if (child.thinking !== thinking) this.#configure({ thinking });
+	}
+
+	close(): void {
+		this.#closed = true;
+	}
+
+	#configure(change: MirrorConfigure): void {
+		this.#mirror.configure(change).catch((cause: unknown) => {
+			this.#notify(cause);
+			const child = this.#mirror.child;
+
+			if (child !== undefined) this.fromAgent(child);
+		});
+	}
+
+	#thinkingFromAgent(child: ChildInfo): void {
+		if (!this.#closed && this.#piHasModel(child) && this.#pi.getThinkingLevel() !== child.thinking) {
+			this.#pi.setThinkingLevel(child.thinking);
+		}
+	}
+
+	#piHasModel(child: ChildInfo): boolean {
+		const model = this.#ctx.model;
+
+		return model?.provider === child.provider && model.id === child.model;
+	}
+}

package/pi/package.json

@@ -1,6 +1,6 @@
 {
 	"private": true,
-	"description": "The Pi extension of harness: the subagent tool, the /subagent command and the subagents widget",
+	"description": "The Pi extension of harness: the subagent tool, the /subagent command, the subagents widget and the /harness mirror sessions",
 	"type": "module",
 	"pi": {
 		"extensions": [
@@ -9,6 +9,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
 	}
 }

package/pi/program-status.ts

@@ -0,0 +1,66 @@
+/**
+ * The state of the agent of a mirror session for the terminal, with the Program Status Protocol (OSC 7501): `working`
+ * while it works, `error` when its last request failed, and `idle` in all other cases.
+ */
+import type { ProgramStatus, Terminal } from "@earendil-works/pi-tui";
+import { type Mirror, targetTitle } from "../dist/mirror.js";
+import { childTitle } from "../dist/protocol.js";
+
+/** The program name of each report. */
+const APP = "harness";
+
+type Mirrored = Pick<Mirror, "target" | "status" | "child" | "view" | "busy">;
+
+/** The title of the agent of `mirror`. */
+function title({ target, child }: Pick<Mirrored, "target" | "child">): string {
+	return child === undefined ? targetTitle(target) : childTitle(child);
+}
+
+/** The first line of the error of the last failed request, or `Error` when there is none. */
+function errorLine({ view }: Pick<Mirrored, "view">): string {
+	const failed = view?.entries.findLast((entry) => {
+		const message = entry.model?.[0];
+
+		return entry.kind === "pi.assistant" && message?.role === "assistant" && message.stopReason === "error";
+	})?.model?.[0];
+
+	const text = failed?.role === "assistant" ? failed.errorMessage : undefined;
+
+	return text?.split(/\r?\n/, 1)[0]?.trim() || "Error";
+}
+
+/** The state of the agent of `mirror`. */
+function programStatus(mirror: Mirrored): ProgramStatus {
+	if (mirror.busy) return { state: "working", app: APP, message: title(mirror) };
+
+	if (mirror.status.kind === "open" && mirror.child?.state === "error") {
+		return { state: "error", app: APP, message: errorLine(mirror) };
+	}
+
+	return { state: "idle", app: APP, message: title(mirror) };
+}
+
+export class ProgramStatusReport {
+	readonly #terminal: Pick<Terminal, "setProgramStatus">;
+	/** The state and the message of the last report. */
+	#last: string | undefined;
+
+	constructor(terminal: Pick<Terminal, "setProgramStatus">) {
+		this.#terminal = terminal;
+	}
+
+	/** Reports the state of the agent of `mirror` when its state or its message changed since the last report. */
+	update(mirror: Mirrored): void {
+		const report = programStatus(mirror);
+		const key = `${report.state}\n${report.message}`;
+
+		if (key === this.#last) return;
+		this.#last = key;
+		this.#terminal.setProgramStatus(report);
+	}
+
+	/** Reports `idle` one more time, when Pi leaves the session of `mirror`. */
+	leave(mirror: Pick<Mirrored, "target" | "child">): void {
+		this.#terminal.setProgramStatus({ state: "idle", app: APP, message: title(mirror) });
+	}
+}

package/pi/usage-line.ts

@@ -0,0 +1,59 @@
+/** The usage line of a mirror session, above the editor, as Pi's footer shows the usage of its own session. */
+import type { ExtensionContext, Theme } 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 ChildInfo, childTitle } from "../dist/protocol.js";
+import { lastAnswerUsage, usageTotals } from "../dist/view-state.js";
+
+/**
+ * The title of the agent, the tokens and the cost of its model requests and tool results, and the context of its last
+ * answer that did not abort or fail, against the context window of its model, as Pi's footer shows them for its own
+ * session.
+ */
+export function usageLine(
+	theme: Theme,
+	models: ExtensionContext["modelRegistry"],
+	child: ChildInfo,
+	view: ConversationView,
+): string {
+	const totals = usageTotals(view);
+	const last = lastAnswerUsage(view);
+	const model = models.find(child.provider, child.model);
+	const subscription = model !== undefined && models.isUsingOAuth(model);
+	const usage: string[] = [];
+
+	if (totals.input) usage.push(`↑${formatTokens(totals.input)}`);
+
+	if (totals.output) usage.push(`↓${formatTokens(totals.output)}`);
+
+	if (totals.cacheRead) usage.push(`R${formatTokens(totals.cacheRead)}`);
+
+	if (totals.cacheWrite) usage.push(`W${formatTokens(totals.cacheWrite)}`);
+
+	if (totals.cost || subscription) usage.push(`$${totals.cost.toFixed(3)}${subscription ? " (sub)" : ""}`);
+	const parts = [childTitle(child)];
+
+	if (usage.length > 0) parts.push(usage.join(" "));
+	const contextWindow = model?.contextWindow ?? 0;
+
+	if (contextWindow > 0) {
+		const percent = last === undefined ? 0 : (coding.calculateContextTokens(last) / contextWindow) * 100;
+		const context = `${percent.toFixed(1)}%/${formatTokens(contextWindow)}`;
+		parts.push(percent > 90 ? theme.fg("error", context) : percent > 70 ? theme.fg("warning", context) : context);
+	}
+
+	return theme.fg("dim", parts.join(" • "));
+}
+
+/** A token count as Pi's footer shows it: `950`, `1.2k`, `45k`, `1.5M`. */
+function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+
+	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+
+	if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+
+	return `${Math.round(count / 1_000_000)}M`;
+}

package/dist/chat.d.ts

@@ -1,48 +0,0 @@
-/**
- * A durable conversation drawn with Pi's own message and tool components.
- *
- * Adapted from `ChatView` in mavam/pi-agents, src/ui/attach.ts. MIT License, Copyright (c) 2026 Matthias Vallentin.
- */
-import type { ToolResultMessage } from "@earendil-works/pi-ai";
-import type { ConversationView } from "@earendil-works/pi-durable";
-import { Container, type TUI } from "@earendil-works/pi-tui";
-/**
- * A tool result as Pi shows its own. pi-durable adds the diagnostics of a call for the model as a `<harness>` block, such
- * as `Command exited with code 3`, and the card shows them as plain lines.
- */
-export declare function displayedResult(result: ToolResultMessage): ToolResultMessage;
-/** The transcript of one conversation view, updated in place as the view changes. */
-export declare class ChatView {
-    readonly transcript: Container;
-    /** The newest card for each call ID: providers can use a call ID again in a later turn. */
-    private readonly tools;
-    /** Every card shown, also the older ones whose call ID a later turn used again. */
-    private readonly cards;
-    /** The cards that have no final result yet. */
-    private readonly running;
-    /** The call IDs whose cards the streamed answer made; its entry takes them over. */
-    private readonly streamingCalls;
-    private readonly renderers;
-    private renderedEntryIds;
-    private streaming;
-    /** Ctrl+O shows tool output in full, as in Pi. */
-    private expanded;
-    private readonly ui;
-    private readonly cwd;
-    constructor(ui: TUI, cwd: string);
-    apply(view: ConversationView): void;
-    /** Shows tool output in full, or collapses it again. */
-    toggleExpanded(): void;
-    /** Finishes the running cards: a running bash card keeps a timer until it gets a final result. */
-    stopTimers(): void;
-    private syncTranscript;
-    private rebuild;
-    private addEntry;
-    private syncStreaming;
-    private renderer;
-    /** The newest card of a call, or a new card when the call has none. */
-    private card;
-    /** A new card of a call, also for a call ID that an earlier turn used. */
-    private newCard;
-    private addText;
-}