@giladbarnea/pi-user-agents 0.0.0

package/context-meter.ts

@@ -0,0 +1,41 @@
+import type { CompletedAgent, RunningAgent, Theme } from "./shared.js";
+
+const CONTEXT_METER_SYMBOLS = [" ", "▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+const CONTEXT_MUTED_THRESHOLD = 40;
+const CONTEXT_WARNING_THRESHOLD = 65;
+const CONTEXT_ERROR_THRESHOLD = 85;
+
+type ContextMeterAgent = RunningAgent | CompletedAgent;
+type ContextMeterColor = "dim" | "muted" | "warning" | "error";
+
+/** @example contextMeterColor(85) // "error" */
+export function contextMeterColor(percent: number): ContextMeterColor {
+	if (percent >= CONTEXT_ERROR_THRESHOLD) return "error";
+	if (percent >= CONTEXT_WARNING_THRESHOLD) return "warning";
+	if (percent >= CONTEXT_MUTED_THRESHOLD) return "muted";
+	return "dim";
+}
+
+export function renderContextMeter(
+	percent: number | null | undefined,
+	theme: Pick<Theme, "fg">,
+): string {
+	if (percent === null || percent === undefined) return "";
+	const boundedPercent = Math.max(0, Math.min(100, percent));
+	const level = Math.min(
+		CONTEXT_METER_SYMBOLS.length - 1,
+		Math.floor(boundedPercent / (100 / CONTEXT_METER_SYMBOLS.length)),
+	);
+	return theme.fg(contextMeterColor(boundedPercent), CONTEXT_METER_SYMBOLS[level]);
+}
+
+/** Render the current or final context usage for either agent state. */
+export function renderAgentContextMeter(
+	agent: ContextMeterAgent,
+	theme: Pick<Theme, "fg">,
+): string {
+	const percent = "status" in agent
+		? agent.session?.getContextUsage()?.percent
+		: agent.contextPercent;
+	return renderContextMeter(percent, theme);
+}

package/editor-coloring.ts

@@ -0,0 +1,160 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { EditorComponent } from "@earendil-works/pi-tui";
+import {
+	type AgentTokenSemantic,
+	type AgentValueValidator,
+	scanAgentCommandLine,
+} from "./command-line.js";
+
+/** The minimal theme surface the coloring layer consumes. */
+export type StyleTheme = { fg(color: ThemeColor, text: string): string };
+
+export const AGENT_SEMANTIC_COLORS: Record<AgentTokenSemantic | "command", ThemeColor> = {
+	command: "accent",
+	option: "syntaxKeyword",
+	value: "syntaxString",
+	"invalid-value": "error",
+	blocked: "error",
+	"misplaced-option": "error",
+	"misplaced-value": "error",
+};
+
+export type AgentColorSpan = { start: number; end: number; color: ThemeColor };
+
+type LayoutLine = { text: string; hasCursor?: boolean; cursorPos?: number };
+type ColoringRuntimeEditor = EditorComponent & {
+	getLines?: () => string[];
+	layoutText?: (contentWidth: number) => LayoutLine[];
+};
+
+const COLORED_EDITOR = Symbol.for("pi-user-agents:coloring-editor");
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+type ColoredEditor = ColoringRuntimeEditor & { [COLORED_EDITOR]?: true };
+
+/**
+ * Map an editor line to theme-colored spans via the shared semantic scan.
+ * Returns undefined for lines that are not agent commands.
+ *
+ * @example computeAgentColorSpans("/agent -m gpt56s go")?.[1] // { start: 7, end: 9, color: "syntaxKeyword" }
+ */
+export function computeAgentColorSpans(
+	line: string,
+	isValueValid?: AgentValueValidator,
+): AgentColorSpan[] | undefined {
+	const scan = scanAgentCommandLine(line, isValueValid);
+	if (!scan) return undefined;
+	const spans: AgentColorSpan[] = [
+		{ start: 0, end: scan.commandEnd, color: AGENT_SEMANTIC_COLORS.command },
+	];
+	for (const token of scan.tokens) {
+		if (token.end > token.start)
+			spans.push({
+				start: token.start,
+				end: token.end,
+				color: AGENT_SEMANTIC_COLORS[token.semantic],
+			});
+	}
+	return spans;
+}
+
+/**
+ * Patch the editor's layout pass to paint agent-command tokens with theme colors.
+ * Layout and wrapping run on the raw text first; styling only rewrites the laid-out
+ * chunk text (and remaps the cursor index) so editing behavior is untouched.
+ */
+export function decorateColoringEditor<T extends EditorComponent>(
+	editor: T,
+	getTheme: () => StyleTheme,
+	isValueValid?: AgentValueValidator,
+): T {
+	const runtimeEditor = editor as T & ColoredEditor;
+	if (runtimeEditor[COLORED_EDITOR]) return editor;
+	const layoutText = runtimeEditor.layoutText;
+	const getLines = runtimeEditor.getLines;
+	if (typeof layoutText !== "function" || typeof getLines !== "function")
+		throw new Error("pi-user-agents coloring requires editor.layoutText() and editor.getLines()");
+	runtimeEditor.layoutText = (contentWidth: number): LayoutLine[] => {
+		const layoutLines = layoutText.call(editor, contentWidth);
+		const line = getLines.call(editor)[0] ?? "";
+		const spans = computeAgentColorSpans(line, isValueValid);
+		if (spans === undefined) return layoutLines;
+		const theme = getTheme();
+		let offset = 0;
+		for (const layoutLine of layoutLines) {
+			const rawLength = layoutLine.text.length;
+			const styled = styleLayoutSlice(
+				layoutLine.text,
+				offset,
+				spans,
+				theme,
+				layoutLine.hasCursor ? layoutLine.cursorPos : undefined,
+			);
+			layoutLine.text = styled.text;
+			if (styled.cursorPos !== undefined) layoutLine.cursorPos = styled.cursorPos;
+			offset += rawLength;
+			if (offset >= line.length) break;
+		}
+		return layoutLines;
+	};
+	runtimeEditor[COLORED_EDITOR] = true;
+	return editor;
+}
+
+/**
+ * Paint one laid-out chunk of the first logical line. The cursor index is remapped to
+ * the styled string and its grapheme is left unpainted, because the editor renders the
+ * cursor by inverse-videoing the first grapheme found at that index.
+ */
+function styleLayoutSlice(
+	text: string,
+	sliceStart: number,
+	spans: readonly AgentColorSpan[],
+	theme: StyleTheme,
+	cursorPos: number | undefined,
+): { text: string; cursorPos?: number } {
+	let styled = "";
+	let styledCursorPos: number | undefined;
+	let index = 0;
+
+	const paint = (segment: string, color: ThemeColor | undefined): void => {
+		if (segment === "") return;
+		styled += color === undefined ? segment : theme.fg(color, segment);
+	};
+	const emitRun = (runEnd: number, color: ThemeColor | undefined): void => {
+		while (index < runEnd) {
+			if (
+				cursorPos !== undefined &&
+				styledCursorPos === undefined &&
+				cursorPos >= index &&
+				cursorPos < runEnd
+			) {
+				paint(text.slice(index, cursorPos), color);
+				styledCursorPos = styled.length;
+				const grapheme = firstGrapheme(text.slice(cursorPos, runEnd));
+				styled += grapheme;
+				index = cursorPos + grapheme.length;
+				continue;
+			}
+			paint(text.slice(index, runEnd), color);
+			index = runEnd;
+		}
+	};
+
+	const sliceEnd = sliceStart + text.length;
+	for (const span of spans) {
+		if (span.end <= sliceStart || span.start >= sliceEnd) continue;
+		const localStart = Math.max(span.start - sliceStart, 0);
+		const localEnd = Math.min(span.end - sliceStart, text.length);
+		emitRun(localStart, undefined);
+		emitRun(localEnd, span.color);
+	}
+	emitRun(text.length, undefined);
+	if (cursorPos !== undefined && styledCursorPos === undefined) styledCursorPos = styled.length;
+	return { text: styled, cursorPos: styledCursorPos };
+}
+
+function firstGrapheme(text: string): string {
+	for (const segment of graphemeSegmenter.segment(text)) return segment.segment;
+	return "";
+}

package/index.ts

@@ -0,0 +1,74 @@
+import type {
+	MessageEndEvent,
+	MessageEndEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { registerAgentAutocomplete } from "./autocomplete.js";
+import { handleAgentCommand } from "./runner.js";
+import type { AgentCommandDetails, ExtensionAPI, RunningAgent } from "./shared.js";
+import { MESSAGE_TYPE } from "./shared.js";
+import { registerUserAgentRenderer } from "./transcript.js";
+import { UserAgentWidget } from "./widget.js";
+
+export default function userAgent(pi: ExtensionAPI): void {
+	const runningAgents = new Set<RunningAgent>();
+	const widget = new UserAgentWidget(runningAgents, (message) =>
+		pi.sendMessage(message, { triggerTurn: true }),
+	);
+	let shuttingDown = false;
+	let nextAgentNumber = 0;
+
+	registerUserAgentRenderer(pi);
+	registerAgentAutocomplete(pi);
+
+	pi.on("message_end", (event) => confirmMainContextJoin(event, widget));
+
+	pi.registerCommand("agent", {
+		description:
+			"Run a background SDK agent with current session context; forwards pi CLI options like --thinking (-i/--isolate for none)",
+		handler: async (args, ctx) => {
+			await handleAgentCommand(
+				pi,
+				runningAgents,
+				widget,
+				() => shuttingDown,
+				() => ++nextAgentNumber,
+				"agent",
+				args,
+				`/agent ${args}`.trim(),
+				ctx,
+			);
+		},
+	});
+
+	pi.on("session_shutdown", async () => {
+		shuttingDown = true;
+		widget.dispose();
+		const agents = [...runningAgents];
+		for (const agent of agents) {
+			void agent.session?.abort();
+			agent.retire?.();
+		}
+		await Promise.allSettled(agents.map((agent) => agent.finished));
+		for (const agent of agents) {
+			agent.session?.dispose();
+		}
+		runningAgents.clear();
+	});
+}
+
+export function confirmMainContextJoin(
+	event: MessageEndEvent,
+	widget: UserAgentWidget,
+): MessageEndEventResult | undefined {
+	if (event.message.role !== "custom" || event.message.customType !== MESSAGE_TYPE) return;
+	const details = event.message.details as AgentCommandDetails | undefined;
+	if (!details?.agentId || details.mainContextState !== "will-join") return;
+	widget.confirmMainContextJoin(details.agentId);
+	details.mainContextState = "joined";
+	return {
+		message: {
+			...event.message,
+			details: { ...details, mainContextState: "joined" },
+		},
+	};
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@giladbarnea/pi-user-agents",
+  "version": "0.0.0",
+  "description": "Run, view, and control background Pi agents.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-agent",
+    "pi-coding-agent",
+    "background-agents",
+    "multi-agent"
+  ],
+  "author": "Gilad Barnea",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giladbarnea/pi-user-agents.git"
+  },
+  "homepage": "https://github.com/giladbarnea/pi-user-agents",
+  "bugs": {
+    "url": "https://github.com/giladbarnea/pi-user-agents/issues"
+  },
+  "files": [
+    "*.ts",
+    "tool-render",
+    "README.md",
+    "PARSER_SPEC.md",
+    "INTERNALS.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}