@giladbarnea/pi-user-agents 0.0.8 → 0.0.9

package/herdr.ts

@@ -0,0 +1,92 @@
+import * as childProcess from "node:child_process";
+
+/** Whether this Pi runs inside a herdr pane, so new panes can be split from it. */
+export function insideHerdr(): boolean {
+	return process.env.HERDR_ENV === "1";
+}
+
+/**
+ * The herdr agent name for a child session. Herdr names must be unique among live agents and
+ * match [a-z][a-z0-9_-]{0,31}; the first 13 characters of a v7 session id hold its complete
+ * millisecond timestamp, so two children never share one.
+ *
+ * @example herdrAgentName("0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce") // "agent-0199c4f2-8b1a"
+ */
+export function herdrAgentName(sessionId: string): string {
+	return `agent-${sessionId.slice(0, 13)}`;
+}
+
+/** Split the calling pane and start `pi <piArgs>` in the new pane; resolves with the pane id once pi is ready. */
+export async function openPiInHerdrPane(
+	cwd: string,
+	agentName: string,
+	piArgs: readonly string[],
+): Promise<string> {
+	const paneId = await splitPane(cwd);
+	await startPi(paneId, agentName, piArgs);
+	return paneId;
+}
+
+/** Split the calling pane without taking the user's focus; resolves with the new pane's id. */
+export async function splitPane(cwd: string): Promise<string> {
+	const direction = await splitDirection();
+	const split = (await herdr([
+		"pane",
+		"split",
+		"--current",
+		"--direction",
+		direction,
+		"--cwd",
+		cwd,
+		"--no-focus",
+	])) as { pane: { pane_id: string } };
+	return split.pane.pane_id;
+}
+
+/** Start `pi <piArgs>` in a shell pane as a named herdr agent; resolves once pi is ready for input. */
+export async function startPi(
+	paneId: string,
+	agentName: string,
+	piArgs: readonly string[],
+): Promise<void> {
+	await herdr(["agent", "start", agentName, "--kind", "pi", "--pane", paneId, "--", ...piArgs]);
+}
+
+type PaneLayout = {
+	panes: Array<{ pane_id: string; rect: { width: number; height: number } }>;
+};
+
+/** A wide pane splits to the right and a narrow or tall one down, so neither half turns unusable. */
+async function splitDirection(): Promise<"right" | "down"> {
+	const { layout } = (await herdr(["pane", "layout", "--current"])) as { layout: PaneLayout };
+	const callerRect = layout.panes.find((pane) => pane.pane_id === process.env.HERDR_PANE_ID)?.rect;
+	if (!callerRect) return "right";
+	return callerRect.width >= callerRect.height * 2 ? "right" : "down";
+}
+
+/** Run one herdr CLI command and return its JSON `result`. Rejects with herdr's own message. */
+function herdr(args: readonly string[]): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		childProcess.execFile("herdr", [...args], (error, stdout, stderr) => {
+			if (error) {
+				reject(new Error(herdrFailureMessage(error, stdout, stderr)));
+				return;
+			}
+			try {
+				resolve((JSON.parse(stdout) as { result: unknown }).result);
+			} catch (parseError) {
+				reject(parseError);
+			}
+		});
+	});
+}
+
+/** Herdr reports server errors as JSON on stderr and usage errors as plain text. */
+function herdrFailureMessage(error: Error, stdout: string, stderr: string): string {
+	const text = (stderr || stdout || error.message).trim();
+	try {
+		return (JSON.parse(text) as { error?: { message?: string } }).error?.message ?? text;
+	} catch {
+		return text;
+	}
+}

package/index.ts

@@ -2,7 +2,7 @@ import type {
 	MessageEndEvent,
 	MessageEndEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { handleAttachCommand } from "./attach.js";
+import { createHerdrDelivery, handleAttachCommand } from "./attach.js";
 import { registerAgentAutocomplete } from "./autocomplete.js";
 import { createRebaseDelivery, handleAgentCommand } from "./runner.js";
 import type {
@@ -25,6 +25,7 @@ export default function userAgent(pi: ExtensionAPI): void {
 		(message) => pi.sendMessage(message, { triggerTurn: true }),
 		(sessionId) => pi.appendEntry<DetachedEntryData>(DETACHED_ENTRY_TYPE, { sessionId }),
 		createRebaseDelivery(pi, () => mainSessionContext),
+		createHerdrDelivery(() => mainSessionContext),
 	);
 	let shuttingDown = false;
 	let nextAgentNumber = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",
@@ -45,7 +45,7 @@
     ]
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2"
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1"
   }
 }

package/runner.ts

@@ -1,3 +1,4 @@
+import { existsSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
@@ -16,7 +17,12 @@ import {
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { type AgentValueValidator, parseAgentCommand } from "./command-line.js";
+import {
+	type AgentValueValidator,
+	forwardedArgsForPane,
+	parseAgentCommand,
+} from "./command-line.js";
+import { herdrAgentName, insideHerdr, openPiInHerdrPane } from "./herdr.js";
 import { conversationFingerprint, mainContextFingerprint } from "./rebase.js";
 import type {
 	AgentCommandName,
@@ -39,6 +45,7 @@ import {
 	errorMessage,
 	formatModel,
 	formatModelLabel,
+	herdrPaneLabel,
 	logSteering,
 	REBASED_ENTRY_TYPE,
 } from "./shared.js";
@@ -91,20 +98,18 @@ async function startUserAgent(
 	ctx: ExtensionCommandContext,
 ): Promise<void> {
 	const parsed = parseAgentCommand(args, command);
+	if (parsed.herdr && !insideHerdr())
+		throw new Error(`/${command} -h needs Pi to run inside a herdr pane`);
 	const parsedForwardedArgs = parseForwardedArgs(parsed.forwardedArgs);
-	const services = await createChildServices(
-		ctx,
-		buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
-	);
-	const forwarded = resolveForwardedOptions(parsedForwardedArgs, services.modelRuntime);
+	const modelRuntime = parentModelRuntime(ctx);
+	const forwarded = resolveForwardedOptions(parsedForwardedArgs, modelRuntime);
 	const selectedModel = forwarded.model ?? ctx.model;
 	if (!selectedModel) throw new Error("No current model is selected; pass -m MODELNAME");
-	const model =
-		services.modelRuntime.getModel(selectedModel.provider, selectedModel.id) ?? selectedModel;
+	const model = modelRuntime.getModel(selectedModel.provider, selectedModel.id) ?? selectedModel;
 	const thinkingLevel = forwarded.thinkingLevel ?? pi.getThinkingLevel();
 	const inheritedMessages = parsed.isolate ? [] : buildInheritedMessages(ctx);
 	// A real session file from birth: the child outlives the widget row and stays resumable.
-	const childSessionManager = SessionManager.create(services.cwd, undefined, {
+	const childSessionManager = SessionManager.create(ctx.cwd, undefined, {
 		parentSession: ctx.sessionManager.getSessionFile(),
 	});
 	// The dispatch record: /agent-attach restores tool and resource options from it later.
@@ -123,11 +128,32 @@ async function startUserAgent(
 		conversationFingerprint(inheritedMessages),
 	);
 
-	runningAgents.add(runningAgent);
-	logSteering(runningAgent.id, "agent-created", { command, taskLength: parsed.task.length });
 	if (ctx.hasUI) {
 		widget.setUI(ctx.ui);
 		for (const warning of parsed.warnings) ctx.ui.notify(warning, "warning");
+	}
+	if (parsed.herdr) {
+		await dispatchToHerdrPane(
+			ctx,
+			widget,
+			childSessionManager,
+			inheritedMessages,
+			model,
+			thinkingLevel,
+			parsed,
+			runningAgent,
+		);
+		return;
+	}
+
+	// The pane's Pi loads its own resources; only a background child needs them here.
+	const services = await createChildServices(
+		ctx,
+		buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
+	);
+	runningAgents.add(runningAgent);
+	logSteering(runningAgent.id, "agent-created", { command, taskLength: parsed.task.length });
+	if (ctx.hasUI) {
 		ctx.ui.notify(formatStartNotification(runningAgent), "info");
 		widget.ensureTimer();
 		widget.update();
@@ -153,6 +179,64 @@ async function startUserAgent(
 	});
 }
 
+/**
+ * An agent born in a herdr pane: the child file is flushed here, then the pane's Pi resumes it
+ * with the dispatch options as CLI flags and takes the preambled task as its first prompt.
+ * Nothing runs in this process, so the widget row is a pointer at the pane from birth.
+ */
+async function dispatchToHerdrPane(
+	ctx: ExtensionCommandContext,
+	widget: UserAgentWidget,
+	childSessionManager: SessionManager,
+	inheritedMessages: AgentMessage[],
+	model: Model,
+	thinkingLevel: ThinkingLevel,
+	parsed: ParsedAgentCommand,
+	runningAgent: RunningAgent,
+): Promise<void> {
+	persistMessages(childSessionManager, inheritedMessages, []);
+	// Pi resumes a session with the model of whichever comes last on the path, a model_change entry
+	// or an assistant message, and writes model_change itself only on its empty-session path. Record
+	// both after the snapshot, or a later /agent-attach or /resume takes main's last answer's model.
+	childSessionManager.appendModelChange(model.provider, model.id);
+	childSessionManager.appendThinkingLevelChange(thinkingLevel);
+	const sessionFile = flushSessionFile(childSessionManager);
+	// Explicit on the CLI too: an isolated child's file has no messages, and pi then takes the
+	// flags over the file.
+	const paneId = await openPiInHerdrPane(ctx.cwd, herdrAgentName(runningAgent.sessionId), [
+		...forwardedArgsForPane(parsed.forwardedArgs),
+		"--provider",
+		model.provider,
+		"--model",
+		model.id,
+		"--thinking",
+		thinkingLevel,
+		"--session",
+		sessionFile,
+		PANE_DISPATCH_PREAMBLE + parsed.task,
+	]);
+	logSteering(runningAgent.id, "agent-dispatched-to-herdr", { paneId });
+	if (!ctx.hasUI) return;
+	widget.addHerdrDispatch(runningAgent, paneId);
+	ctx.ui.notify(`Started /${runningAgent.command} in ${herdrPaneLabel(paneId)}`, "info");
+}
+
+/**
+ * Make sure a child session file is on disk. Pi defers the file until the first assistant
+ * message, so a child whose inherited context has none is still in memory only, while a Pi in
+ * another pane can only resume a file that exists.
+ */
+export function flushSessionFile(sessionManager: SessionManager): string {
+	const sessionFile = sessionManager.getSessionFile();
+	if (!sessionFile) throw new Error("The child session has no file path");
+	if (existsSync(sessionFile)) return sessionFile;
+	const lines = [sessionManager.getHeader(), ...sessionManager.getEntries()].map(
+		(entry) => `${JSON.stringify(entry)}\n`,
+	);
+	writeFileSync(sessionFile, lines.join(""), { flag: "wx" });
+	return sessionFile;
+}
+
 function createRunningAgent(
 	sequenceNumber: number,
 	sessionId: string,
@@ -296,13 +380,19 @@ export function createChildServices(
 		cwd: ctx.cwd,
 		agentDir,
 		settingsManager,
-		// The extension facade wraps the parent's runtime as a plain property; sharing it keeps
-		// extension-registered providers (their process-global dedup guard) available to the child.
-		modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
+		modelRuntime: parentModelRuntime(ctx),
 		resourceLoaderOptions,
 	});
 }
 
+/**
+ * The parent's ModelRuntime: the extension facade wraps it as a plain property. Sharing it keeps
+ * extension-registered providers (their process-global dedup guard) available to the child.
+ */
+function parentModelRuntime(ctx: ExtensionCommandContext): ModelRuntime {
+	return (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime;
+}
+
 /** Parse forwarded pi CLI tokens once before model and session resolution. */
 export function parseForwardedArgs(forwardedArgs: string[]): Args {
 	const parsed = parseArgs(forwardedArgs);
@@ -516,9 +606,13 @@ export function reportAgentFailure(
 		runningAgent.status = "posted";
 }
 
-/** Every dispatch prefixes its task with this; attach recognizes it as the child's dispatch boundary. */
+/** Every background dispatch prefixes its task with this; attach recognizes it as the child's dispatch boundary. */
 export const DISPATCH_PREAMBLE =
 	"You are running in an ephemeral, forked background process now, concurrently with the main session. ";
+/** The -h dispatch's preamble: that child is interactive, and the user may talk to it in its pane. */
+export const PANE_DISPATCH_PREAMBLE =
+	"You are running in a forked session now, in a herdr pane beside the main session. The user may talk to you here. ";
+export const DISPATCH_PREAMBLES = [DISPATCH_PREAMBLE, PANE_DISPATCH_PREAMBLE] as const;
 
 /** Run turns on an initialized child session until it posts, retires, or shuts down. The initial instruction is sent verbatim. */
 export async function runChildTurns(

package/shared.ts

@@ -28,6 +28,8 @@ export type AgentStatus =
 export type ParsedAgentCommand = {
 	isolate: boolean;
 	squash: boolean;
+	/** -h/--herdr: open the agent in a new herdr pane instead of running it in the background. */
+	herdr: boolean;
 	/** Leading pi CLI tokens (minus the extension's own options) to forward to the child, e.g. ["--thinking", "high"]. */
 	forwardedArgs: string[];
 	task: string;
@@ -162,6 +164,8 @@ export type CompletedAgent = {
 	toolUses: number;
 	turnCount: number;
 	contextPercent?: number;
+	/** The herdr pane whose Pi now owns the session, once the agent was opened there. */
+	herdrPane?: string;
 };
 
 /** The mechanism that fast-forwards a child conversation onto the main session, injected into the widget. */
@@ -172,6 +176,21 @@ export type RebaseDelivery = {
 	deliver(agent: RunningAgent | CompletedAgent, messages: AgentMessage[]): void;
 };
 
+/** A pane split for an agent, whose Pi starts only once the agent's session is free here. */
+export type HerdrPane = {
+	paneId: string;
+	/** Start pi on the agent's session file in this pane; resolves once it is ready for input. */
+	start(): Promise<void>;
+};
+
+/** The mechanism that hands an agent's session to a Pi in a new herdr pane, injected into the widget. */
+export type HerdrDelivery = {
+	/** Whether this Pi runs inside a herdr pane, so new panes can be split from it. */
+	available(): boolean;
+	/** Resolve the agent's session file and split a pane for it; rejects before splitting when there is no file. */
+	split(agent: RunningAgent | CompletedAgent): Promise<HerdrPane>;
+};
+
 /** How long a confirmation stays armed, and how long a transient footer notice shows. */
 export const CONFIRMATION_WINDOW_MS = 4000;
 
@@ -266,6 +285,13 @@ export function mainContextLabel(state: MainContextState | undefined): string |
 	return undefined;
 }
 
+/**
+ * @example herdrPaneLabel("w1:p3") // "herdr pane w1:p3"
+ */
+export function herdrPaneLabel(paneId: string): string {
+	return `herdr pane ${paneId}`;
+}
+
 export function formatTurns(turnCount: number): string {
 	return `↻${turnCount}`;
 }