@giladbarnea/pi-user-agents 0.0.0

package/shared.ts

@@ -0,0 +1,214 @@
+import { appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import type {
+	AgentSession,
+	buildSessionContext,
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+export type { AgentSession, ExtensionAPI, ExtensionCommandContext };
+
+export type AgentMessage = ReturnType<typeof buildSessionContext>["messages"][number];
+export type Model = NonNullable<ExtensionCommandContext["model"]>;
+export type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
+export type Theme = ExtensionCommandContext["ui"]["theme"];
+export type UIContext = ExtensionCommandContext["ui"];
+
+export type AgentCommandName = "agent";
+export type MainContextState = "separate" | "will-join" | "joined";
+export type AgentStatus =
+	| "starting"
+	| "running"
+	| "done-waiting-to-post"
+	| "idle"
+	| "posted"
+	| "error";
+
+export type ParsedAgentCommand = {
+	isolate: boolean;
+	context: boolean;
+	/** Leading pi CLI tokens (minus the extension's own options) to forward to the child, e.g. ["--thinking", "high"]. */
+	forwardedArgs: string[];
+	task: string;
+	/** Advisory messages surfaced to the user (e.g. a recognized option was typed inside the prose body). */
+	warnings: string[];
+};
+
+export type AgentEntryData = {
+	content: string;
+	details: AgentCommandDetails;
+};
+
+export type AgentResultMessage = {
+	customType: string;
+	content: string;
+	display: boolean;
+	details: AgentCommandDetails;
+};
+
+export type AgentCommandDetails = {
+	agentId?: string;
+	command: AgentCommandName;
+	mainContextState?: MainContextState;
+	inheritedContext: boolean;
+	model: string;
+	modelLabel: string;
+	task: string;
+	ok: boolean;
+	durationMs?: number;
+	toolUses?: number;
+	turnCount?: number;
+	responseText?: string;
+	/** Retained for completed entries written before responseText was persisted. */
+	responsePreview?: string;
+	error?: string;
+};
+
+export type RunningAgent = {
+	id: string;
+	command: AgentCommandName;
+	inheritedContext: boolean;
+	model: string;
+	modelLabel: string;
+	task: string;
+	/** The slash command line as the user typed it, e.g. `/agent -j fix the bug`. */
+	invocation: string;
+	/** -j/--join: post invocation+result to the main agent and trigger its turn, instead of waiting quietly for the next user prompt. */
+	notifyMainAgent: boolean;
+	mainContextState: MainContextState;
+	status: AgentStatus;
+	startedAt: number;
+	/** Start of the current turn — equals startedAt until the user resumes an idle agent. */
+	turnStartedAt: number;
+	completedAt?: number;
+	activeTools: Map<string, string>;
+	toolUses: number;
+	turnCount: number;
+	responseText: string;
+	/** Append-only child conversation, independent from model context compaction. */
+	conversationMessages: AgentMessage[];
+	latestFinalizedMessage?: AgentMessage;
+	error?: string;
+	session?: AgentSession;
+	/** Latest completed turn's result message, deliverable to the main agent via the overlay's join action. */
+	pendingJoinMessage?: AgentResultMessage;
+	/** Starts another turn on an idle agent; assigned while the lifecycle loop awaits the next instruction. */
+	resume?: (instruction: string) => void;
+	/** Ends an idle agent's lifecycle without another turn; assigned alongside resume. */
+	retire?: () => void;
+	finished: Promise<void>;
+	/** Set when the user closes an in-flight agent from the widget — suppresses the error entry and transcript post. */
+	aborted?: boolean;
+	/** Set when the user interrupts only the active turn, leaving the child session alive. */
+	interruptRequested?: boolean;
+};
+
+export type CompletedAgent = {
+	id: string;
+	command: AgentCommandName;
+	modelLabel: string;
+	task: string;
+	mainContextState: MainContextState;
+	pendingJoinMessage?: AgentResultMessage;
+	ok: boolean;
+	responseText: string;
+	messages: AgentMessage[];
+	error?: string;
+	startedAt: number;
+	durationMs: number;
+	toolUses: number;
+	turnCount: number;
+	contextPercent?: number;
+};
+
+export const MESSAGE_TYPE = "pi-user-agents";
+export const WIDGET_KEY = "pi-user-agents";
+export const STEERING_LOG_PATH = `${tmpdir()}/pi-user-agents-steer.log`;
+
+export function logSteering(
+	agentId: string,
+	event: string,
+	details: Record<string, unknown> = {},
+): void {
+	void appendFile(
+		STEERING_LOG_PATH,
+		`${new Date().toISOString()} ${JSON.stringify({ agentId, event, ...details })}\n`,
+	).catch(() => undefined);
+}
+export const MAX_WIDGET_LINES = 9;
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export const TOOL_DISPLAY: Record<string, string> = {
+	read: "reading",
+	bash: "running command",
+	edit: "editing",
+	write: "writing",
+	grep: "searching",
+	find: "finding files",
+	ls: "listing",
+};
+
+export function formatModel(model: Model): string {
+	return `${model.provider}/${model.id}${model.name && model.name !== model.id ? ` (${model.name})` : ""}`;
+}
+
+export function formatModelLabel(model: Model): string {
+	return model.name && model.name !== model.id ? model.name : model.id;
+}
+
+export function contextLabel(inheritedContext: boolean): string {
+	return inheritedContext ? "inherited context" : "isolated";
+}
+
+export function mainContextLabel(state: MainContextState | undefined): string | undefined {
+	if (state === "will-join") return "will join context";
+	if (state === "joined") return "joined context";
+	return undefined;
+}
+
+export function formatTurns(turnCount: number): string {
+	return `↻${turnCount}`;
+}
+
+export function formatToolUses(toolUses: number): string {
+	return `${toolUses} tool use${toolUses === 1 ? "" : "s"}`;
+}
+
+export function formatMs(ms: number): string {
+	if (!Number.isFinite(ms)) return "0.0s";
+	if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+	const minutes = Math.floor(ms / 60_000);
+	const seconds = Math.round((ms % 60_000) / 1000);
+	return `${minutes}m ${seconds}s`;
+}
+
+export function truncatePlain(text: string, length: number): string {
+	const line =
+		text
+			.split("\n")
+			.find((part) => part.trim())
+			?.trim() ?? "";
+	if (line.length <= length) return line;
+	return `${line.slice(0, Math.max(0, length - 1))}…`;
+}
+
+export function extractTag(
+	content: string,
+	tag: "task" | "response" | "error" | "duration_ms",
+): string | undefined {
+	const match = content.match(new RegExp(`<${tag}>\\n?([\\s\\S]*?)\\n?</${tag}>`));
+	return match?.[1]?.trim();
+}
+
+export function escapeAttribute(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/tool-render/FORK.md

@@ -0,0 +1,108 @@
+---
+description: Provenance and boundary for the overlay's vendored historical tool renderer
+last_updated: 2026-07-31
+---
+# The overlay renders tool history itself
+
+The `/agent` overlay shows a captured child-session transcript. It is not the live transcript.
+It has no tool registry, no execution state, and no component lifecycle. `AgentViewer` produces
+a `string[]`, and the overlay hard-cuts every line to its own width instead of wrapping it.
+
+That is why this module exists. Pi's `ToolExecutionComponent` resolves current tool definitions
+and models live execution, so it cannot render a finished child session whose tools may no
+longer be registered.
+
+## Sources
+
+- `../rich-tool-diff/` — `read`, `edit`, `write`, `grep`, `find`, `ls`.
+- `/Users/giladbarnea/.pi/agent/extensions/bash-rich-highlight/index.ts` — `bash`.
+
+Both are **disabled** in committed `agent/settings.json`, while `pi-user-agents` is enabled.
+Nothing here imports from either at runtime. The code was copied and adapted, by request.
+
+1973 lines here, from 2857 lines of source.
+
+## The contract this module guarantees
+
+1. Pure. No filesystem access, no `process.stdout`, no timers, no tool registry.
+2. Every returned line fits the supplied width and contains no newline.
+3. Calls pair with results by `ToolCall.id` only. Order is never a fallback, because parallel
+   tool calls make it ambiguous. An unpaired call genuinely has no stored result.
+4. Rendering is always expanded, and never mentions an expand key. The overlay has no such key.
+5. Every cap counts **rows drawn**, not lines stored. One line of minified output or one long
+   command wraps into many rows at overlay width, so a cap on stored lines caps nothing.
+
+## What was deliberately left behind
+
+### Live-execution machinery, which has no meaning for history
+
+Tool registration wrappers, pending and partial rendering paths, the blink timer, the bash
+duration timer, and expand-key hints. `attachDiffDetails`, `readTextForDiff` and
+`existingSmallTextOrUndefined` read the current filesystem, which is wrong for a transcript
+recorded earlier — the file may have changed or been deleted since.
+
+### Settings and glyph lookups, replaced by flat constants
+
+`readVstackConfig()` walks parent directories, stats files, reads JSON and parses it, on every
+call. `glyphs(cwd)` sits under several per-line helpers. The overlay re-renders about ten times
+a second, so `constants.ts` holds fixed values instead.
+
+Dropping the setting lookups also dropped the ASCII glyph mode. The overlay frame already draws
+Unicode box characters unconditionally, so that branch was unreachable — and removing it took
+the `cwd` argument out of roughly thirty signatures.
+
+### Terminal-width reads
+
+`renderStructuredDiff()` upstream ignores the width its caller passes and reads
+`process.stdout.columns`. Inside a 90%-width overlay that pads rows past the frame, and the
+overlay then silently cuts their right side. Here the width is a required argument.
+
+### Path hyperlinks and Nerd Font icons
+
+OSC 8 hyperlinks are zero-width escapes threading through padding and truncation arithmetic
+that the overlay performs itself, in a viewport where clicking a path is marginal. The icon
+table needs a Nerd Font and renders as tofu without one. Dropping hyperlinks also removed the
+last need for a `cwd` argument.
+
+### highlight.js
+
+`bash-rich-highlight/index.ts` imports highlight.js through an absolute path inside the global Pi
+installation, then hand-parses its HTML output into ANSI — about 180 lines. That import breaks
+when the installation prefix or the Pi version changes. Pi's own exported
+`highlightCode(command, "bash")` returns `string[]` directly.
+
+### Bash git-diff detection
+
+`renderBashDiffOutput` is gated behind `renderBashDiffs`, which defaults to false.
+
+### Images
+
+`OverlayAwareImage` already suppresses images while a floating overlay is active.
+
+## Kept, against expectation
+
+**Split diffs.** They only engage at 132 columns or more, which a wide-terminal overlay reaches.
+
+**Diff backgrounds.** `applyFullLineBg` re-opens the background after every escape that resets
+it, so a row carrying syntax highlighting, word-diff highlighting and a row tint stays intact.
+`theme.bg` is optional in `RenderTheme`: a theme without it falls back to fixed colours, which
+is also what keeps the module renderable under a test theme.
+
+## Behaviour that intentionally differs from the sources
+
+1. Unknown tools show `key=value` arguments. Nested containers become `{2 keys}` or
+   `[3 items]`, never serialized JSON — a JSON blob is the exact thing this renderer removes.
+2. A bash result whose exit code is `0` renders as success. The sources render `✗ exit 0`.
+3. A call with no stored result says `no result` rather than trailing off after the headline.
+
+## Where this is used
+
+`widget.ts` calls it from two places, and both must stay in step:
+
+- `AgentViewer.messageLines()` — the transcript body.
+- `describeAssistantPart()` — the one-line activity row under the editor.
+
+`AgentViewer` memoizes rendered content, because rich diff rendering is far too costly for the
+widget's 100 ms tick. The memo key covers width, message count, the last message's content
+length, agent status, response length and error length. Streamed content only grows, so a
+length is a sufficient change signal for the streaming tail.

package/tool-render/ansi.ts

@@ -0,0 +1,77 @@
+import {
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+export const ANSI_BG_RESET = "\x1b[49m";
+
+/** Private-use character used to locate where a theme's escape codes open and close. */
+export const STYLE_MARKER = "\uE000";
+
+const ANSI_RE = /\x1b(?:\[[0-9;:]*m|\]133;[ABC]\x07|\]8;[^\x07\x1b]*(?:\x07|\x1b\\))/g;
+const ANSI_PRESENT_RE = /\x1b\[[0-9;]*m/;
+
+export interface AnsiParts {
+	close: string;
+	open: string;
+}
+
+export function stripAnsi(text: string): string {
+	return text.replace(ANSI_RE, "");
+}
+
+export function hasAnsi(text: string): boolean {
+	return ANSI_PRESENT_RE.test(text);
+}
+
+export function visibleLength(text: string): number {
+	return visibleWidth(text);
+}
+
+/** @example padVisible("ab", 4) // "ab  " */
+export function padVisible(text: string, width: number): string {
+	const missing = width - visibleLength(text);
+	return missing > 0 ? `${text}${" ".repeat(missing)}` : text;
+}
+
+export function truncateAnsi(text: string, width: number): string {
+	return truncateToWidth(text, Math.max(1, width), "");
+}
+
+/** Split a styled marker string into the escape codes that open and close it. */
+export function ansiPartsFromStyled(styled: string): AnsiParts {
+	const markerIndex = styled.indexOf(STYLE_MARKER);
+	if (markerIndex < 0) return { open: "", close: "" };
+	return {
+		open: styled.slice(0, markerIndex),
+		close: styled.slice(markerIndex + STYLE_MARKER.length),
+	};
+}
+
+export function ansiHasBackground(open: string): boolean {
+	for (const match of open.matchAll(/\x1b\[([0-9;:]*)m/g)) {
+		const params = match[1] || "0";
+		if (/(^|[;:])48([;:]|$)/.test(params)) return true;
+		if (/(^|[;:])(?:4[0-7]|10[0-7])([;:]|$)/.test(params)) return true;
+	}
+	return false;
+}
+
+export function sgrClearsBackground(code: string): boolean {
+	const match = code.match(/^\x1b\[([0-9;]*)m$/);
+	if (!match) return false;
+	const params = match[1] ? match[1].split(";").map((value) => Number.parseInt(value || "0", 10)) : [0];
+	return params.some((value) => value === 0 || value === 49);
+}
+
+/** Track which foreground style is active so word-diff highlighting can restore it. */
+export function updateActiveAnsiStyle(code: string): string {
+	const match = code.match(/^\x1b\[([0-9;]*)m$/);
+	if (!match) return "";
+	const params = match[1] ? match[1].split(";").map((value) => Number.parseInt(value || "0", 10)) : [0];
+	if (params.some((value) => value === 0 || value === 39)) return "";
+	return code;
+}
+
+export { truncateToWidth, visibleWidth, wrapTextWithAnsi };

package/tool-render/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Flat constants for the overlay's historical tool renderer.
+ *
+ * The source extensions read these from `.pi/settings.json` on every call, walking parent
+ * directories and parsing JSON. The overlay re-renders about ten times per second, so it
+ * uses fixed values instead. It also renders only Unicode glyphs, because the overlay frame
+ * already draws Unicode box characters unconditionally.
+ */
+
+export const GLYPHS = {
+	bullet: "● ",
+	dot: " · ",
+	ellipsis: "…",
+	fail: "✗",
+	line: "─",
+	ok: "✓",
+	tree: { mid: "├─ ", last: "└─ ", stem: "│  " },
+} as const;
+
+/** The overlay is a scrollable inspection surface, so caps are small on purpose. */
+export const CAPS = {
+	/** Diff rows per edit or write result. The source extension allows 4000. */
+	diffRows: 120,
+	/** Preview lines under a `read` result. The source extension allows 80. */
+	readPreviewLines: 20,
+	/** Preview lines under a `grep`, `find`, or `ls` result. The source extension allows 80. */
+	searchPreviewLines: 20,
+	/**
+	 * Rows drawn inside a `bash` result frame. The source extension allows every line.
+	 *
+	 * This counts drawn rows, not stored lines. One stored line of minified output wraps into
+	 * many rows at overlay width, so capping stored lines caps nothing.
+	 */
+	bashOutputRows: 40,
+	/** Rows drawn inside a `bash` command frame, counted the same way. */
+	bashCommandRows: 20,
+	/** Output lines for a tool with no first-class renderer. */
+	genericResultLines: 12,
+	/** Characters of a single output line before it is clipped. */
+	maxLineWidth: 1000,
+	/** Characters of a `bash` command shown in the headline. */
+	commandPreviewChars: 96,
+	/** Characters of serialized arguments shown by the generic fallback. */
+	genericArgumentChars: 160,
+} as const;
+
+/** Diff tables narrower than this render unified instead of side by side. */
+export const DIFF_SPLIT_MIN_WIDTH = 132;