@giladbarnea/pi-user-agents 0.0.3 → 0.0.4

package/INTERNALS.md

@@ -30,6 +30,23 @@ A plain `<user_agent>` tag follows it. The tag contains only the model and inher
 
 One selection rule builds the body. It keeps every user message. Before each next user message, it keeps only the latest assistant response. It applies the same rule after the final user message. Tool calls, thinking, tool results, and other message roles stay out.
 
+## Child session persistence
+
+Every dispatched agent gets a persisted `SessionManager.create(cwd, undefined, { parentSession })` rather than an in-memory one, so its conversation is an ordinary Pi session file from birth. `parentSession` is a *path*, and it records the main session that dispatched the agent — the same field `/fork` uses, surfaced by `SessionManager.list()` as `parentSessionPath`. There is no API to promote an in-memory session to disk later: `SessionManager` fixes `persist` at construction, and both `_persist()` and `_rewriteFile()` return early when it is false, so `setSessionFile()` on an in-memory manager sets a path and writes nothing.
+
+Two ordering constraints follow from `createAgentSession`:
+
+1. **Build the session while its manager is still empty.** Pi writes the `model_change` and `thinking_level_change` entries only on the empty-session path. Seed messages first and those entries never appear, so a resumed child falls back to `findInitialModel` instead of the model it was dispatched with.
+2. **Route the inherited snapshot through the session manager.** Persistence runs off message events, so the old `session.agent.state.messages = inherited` assignment never reached the file. `persistInheritedMessages` appends it entry by entry, then the agent state is set to the same list.
+
+That snapshot is already compaction-resolved, so at most one `compactionSummary` leads it. Each role takes its own append method — `appendCompaction`, `branchWithSummary`, `appendCustomMessageEntry`, `appendMessage` — because pi's own compaction and branch bookkeeping locates boundaries by entry type, and a summary written as a plain message entry would be invisible to it. `appendCompaction` wants a `firstKeptEntryId` the replay cannot know, but `buildContextEntries` only consults it for entries *before* the compaction entry; a leading compaction has none, so the value is never read.
+
+The file itself appears on the child's first assistant message (`_persist` defers until then). An agent dispatched with `-i` that never answers therefore leaves nothing behind, while an agent that inherited context has a file immediately.
+
+## Detaching
+
+`d` `d` ends the live child session and drops its widget row. The session file is untouched, and the transcript gets a `pi-user-agents-detached` custom entry naming the session id so it can be resumed later. Both detach paths funnel through `closeRunning` and `removeCompleted`, which is where the announcement is made; joining and session shutdown deliberately do not announce.
+
 ## Runtime sharing
 
 Child agent sessions share the parent's `ModelRuntime` instance. This is critical because extension-registered providers (like `claude-bridge`) use a global `Symbol.for` dedup guard — they register once per process and skip subsequent loads. A child session with its own fresh runtime would never receive the provider, leaving it without auth for bridge-backed models.

package/README.md

@@ -64,9 +64,19 @@ A background agent is not fire-and-forget — it's a session you can talk to.
 
 Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need; every completed turn posts its own result card.
 
-`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or disposal. In fact, nothing disposes an agent except you: pressing `x` twice, joining it, or ending the Pi session.
+`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or detaching. In fact, nothing ends an agent except you: pressing `d` twice, joining it, or ending the Pi session.
 
-### 4. Join — or don't
+### 4. Detach
+
+Every dispatched agent gets its own Pi session on disk, exactly like the one you're sitting in. When a row has served its purpose, press `d` twice: the agent stops, its row leaves the widget, and its session file is left untouched. The transcript records which one it was:
+
+```
+Detached session 0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce
+```
+
+Pick it back up whenever you like — `/resume 0199c4f2`, or `pi -r` and choose it from the list. It resumes as an ordinary Pi session with its full history, its model, and its thinking level, and from there it is a normal agent you talk to directly.
+
+### 5. Join — or don't
 
 This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
 
@@ -113,7 +123,7 @@ Everything goes through one command: `/agent [options] <task>`.
 | Editor | `←` / `↓` | Focus the agents widget |
 | Widget | `↑` `↓` · `Enter` | Select an agent · open its overlay |
 | Widget / overlay | `Ctrl+x` | Interrupt the current turn (agent stays alive) |
-| Widget / overlay | `x` `x` | Dispose the agent (twice to confirm) |
+| Widget / overlay | `d` `d` | Detach the agent, keeping its session (twice to confirm) |
 | Widget / overlay | `Esc` | Back |
 | Overlay | `Enter` | Steer mid-turn, or start another turn when idle |
 | Overlay | `j` | Join the conversation into the main context |
@@ -122,7 +132,8 @@ Everything goes through one command: `/agent [options] <task>`.
 
 ## Good to know
 
-- Result cards persist across session reloads; live agent sessions don't. After a reload you keep every card, not the steerable sessions.
+- Every dispatch writes a real session file, so dispatched agents show up in `/resume` and `pi -r` alongside your own sessions. An agent that never answered leaves no file.
+- Result cards persist across session reloads; the widget doesn't. After a reload you keep every card, and every agent's session is still on disk — but the steerable rows are gone. Reach them with `/resume`.
 - Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet.
 - `c` copies via `pbcopy`, so it's macOS-only for now.
 - The overlay caps very large tool outputs and omits thinking entries.

package/agent-viewer.ts

@@ -32,7 +32,7 @@ import {
 } from "./tool-render/index.js";
 
 export type ViewableAgent = RunningAgent | CompletedAgent;
-export type AgentViewerAction = "hide" | "dispose";
+export type AgentViewerAction = "hide" | "detach";
 
 export type ActivityDescription = {
 	text: string;
@@ -141,7 +141,7 @@ function truncateMiddle(
 
 const VIEWER_CHROME_LINES = 6;
 const VIEWER_MIN_VIEWPORT = 3;
-const VIEWER_HEIGHT_PCT = 70;
+const VIEWER_HEIGHT_PCT = 85;
 
 /** Focus-capturing overlay that shows an agent's live or finished response. */
 export class AgentViewer implements Component {
@@ -149,7 +149,7 @@ export class AgentViewer implements Component {
 	private autoScroll = true;
 	private lastWidth = 0;
 	private justCopied = false;
-	private confirmingDispose = false;
+	private confirmingDetach = false;
 	private composer: Input | undefined;
 	/** Rich tool rendering is far too costly to repeat on every 100 ms widget tick. */
 	private renderedContent: { key: string; lines: string[] } | undefined;
@@ -166,22 +166,22 @@ export class AgentViewer implements Component {
 
 	handleInput(data: string): void {
 		if (matchesKey(data, "ctrl+x") && isLiveAgent(this.agent)) {
-			this.confirmingDispose = false;
+			this.confirmingDetach = false;
 			this.interrupt();
 			this.tui.requestRender();
 			return;
 		}
 		if (this.composer) {
-			this.confirmingDispose = false;
+			this.confirmingDetach = false;
 			this.composer.handleInput(data);
 			this.tui.requestRender();
 			return;
 		}
-		if (matchesKey(data, "x")) {
-			this.requestDispose();
+		if (matchesKey(data, "d")) {
+			this.requestDetach();
 			return;
 		}
-		this.confirmingDispose = false;
+		this.confirmingDetach = false;
 		if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 			this.done("hide");
 			return;
@@ -253,6 +253,7 @@ export class AgentViewer implements Component {
 			renderAgentContextMeter(this.agent, th),
 			th.fg("dim", status),
 			...stats.map((stat) => th.fg("dim", stat)),
+			th.fg("dim", this.agent.sessionId),
 		]
 			.filter(Boolean)
 			.join(` ${th.fg("dim", "·")} `);
@@ -310,8 +311,8 @@ export class AgentViewer implements Component {
 					mainContext ? th.fg("dim", mainContext) : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Esc hide") : "",
 					th.fg(
-						this.confirmingDispose ? "error" : "dim",
-						this.confirmingDispose ? "x again to confirm" : "x dispose",
+						this.confirmingDetach ? "error" : "dim",
+						this.confirmingDetach ? "d again to confirm" : "d detach",
 					),
 				].filter(Boolean),
 			);
@@ -325,12 +326,12 @@ export class AgentViewer implements Component {
 
 	dispose(): void {}
 
-	private requestDispose(): void {
-		if (this.confirmingDispose) {
-			this.done("dispose");
+	private requestDetach(): void {
+		if (this.confirmingDetach) {
+			this.done("detach");
 			return;
 		}
-		this.confirmingDispose = true;
+		this.confirmingDetach = true;
 		this.tui.requestRender();
 	}
 

package/index.ts

@@ -4,15 +4,22 @@ import type {
 } 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 type {
+	AgentCommandDetails,
+	DetachedEntryData,
+	ExtensionAPI,
+	RunningAgent,
+} from "./shared.js";
+import { DETACHED_ENTRY_TYPE, 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 }),
+	const widget = new UserAgentWidget(
+		runningAgents,
+		(message) => pi.sendMessage(message, { triggerTurn: true }),
+		(sessionId) => pi.appendEntry<DetachedEntryData>(DETACHED_ENTRY_TYPE, { sessionId }),
 	);
 	let shuttingDown = false;
 	let nextAgentNumber = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",

package/runner.ts

@@ -96,7 +96,18 @@ async function startUserAgent(
 		services.modelRuntime.getModel(selectedModel.provider, selectedModel.id) ?? selectedModel;
 	const thinkingLevel = forwarded.thinkingLevel ?? pi.getThinkingLevel();
 	const inheritedMessages = parsed.isolate ? [] : buildInheritedMessages(ctx);
-	const runningAgent = createRunningAgent(nextAgentNumber(), command, model, parsed, invocation);
+	// A real session file from birth: the child outlives the widget row and stays resumable.
+	const childSessionManager = SessionManager.create(services.cwd, undefined, {
+		parentSession: ctx.sessionManager.getSessionFile(),
+	});
+	const runningAgent = createRunningAgent(
+		nextAgentNumber(),
+		childSessionManager.getSessionId(),
+		command,
+		model,
+		parsed,
+		invocation,
+	);
 
 	runningAgents.add(runningAgent);
 	logSteering(runningAgent.id, "agent-created", { command, taskLength: parsed.task.length });
@@ -117,6 +128,7 @@ async function startUserAgent(
 		forwarded,
 		inheritedMessages,
 		services,
+		childSessionManager,
 		runningAgent,
 		widget,
 	).finally(() => {
@@ -129,6 +141,7 @@ async function startUserAgent(
 
 function createRunningAgent(
 	sequenceNumber: number,
+	sessionId: string,
 	command: AgentCommandName,
 	model: Model,
 	parsed: ParsedAgentCommand,
@@ -136,6 +149,7 @@ function createRunningAgent(
 ): RunningAgent {
 	return {
 		id: `user-${sequenceNumber.toString(36)}`,
+		sessionId,
 		command,
 		inheritedContext: !parsed.isolate,
 		model: formatModel(model),
@@ -342,6 +356,7 @@ async function runAgentLifecycle(
 	forwarded: ForwardedOptions,
 	inheritedMessages: AgentMessage[],
 	services: AgentSessionServices,
+	childSessionManager: SessionManager,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<void> {
@@ -354,6 +369,7 @@ async function runAgentLifecycle(
 			forwarded,
 			inheritedMessages,
 			services,
+			childSessionManager,
 			runningAgent,
 			widget,
 		);
@@ -487,12 +503,15 @@ async function createChildSession(
 	forwarded: ForwardedOptions,
 	inheritedMessages: AgentMessage[],
 	services: AgentSessionServices,
+	childSessionManager: SessionManager,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<AgentSession> {
+	// Built while the session is still empty: that is the only path on which pi records the
+	// model and thinking level, and without those entries a resumed child falls back to defaults.
 	const { session } = await createAgentSessionFromServices({
 		services,
-		sessionManager: SessionManager.inMemory(services.cwd),
+		sessionManager: childSessionManager,
 		model,
 		thinkingLevel,
 		tools: forwarded.tools,
@@ -509,12 +528,38 @@ async function createChildSession(
 	await session.bindExtensions({ mode: "print" });
 	logSteering(runningAgent.id, "session-bound", { streaming: session.isStreaming });
 	if (inheritedMessages.length > 0) {
+		persistInheritedMessages(childSessionManager, inheritedMessages);
 		session.agent.state.messages = inheritedMessages;
 		logSteering(runningAgent.id, "context-inherited", { messageCount: inheritedMessages.length });
 	}
 	return session;
 }
 
+/**
+ * Mirror the inherited snapshot into the child's session file so a resumed child sees the
+ * same conversation the live one saw. Each role goes through its own append method: the
+ * snapshot is already compaction-resolved, so its summary leads the child's own branch.
+ */
+export function persistInheritedMessages(
+	sessionManager: SessionManager,
+	messages: readonly AgentMessage[],
+): void {
+	for (const message of messages) {
+		if (message.role === "compactionSummary")
+			sessionManager.appendCompaction(message.summary, "", message.tokensBefore);
+		else if (message.role === "branchSummary")
+			sessionManager.branchWithSummary(sessionManager.getLeafId(), message.summary);
+		else if (message.role === "custom")
+			sessionManager.appendCustomMessageEntry(
+				message.customType,
+				message.content,
+				message.display,
+				message.details,
+			);
+		else sessionManager.appendMessage(message);
+	}
+}
+
 /** Parks an idle agent until the user resumes it with another instruction (resolves with it) or retires it (resolves undefined). */
 export function waitForInstruction(
 	agent: RunningAgent,

package/shared.ts

@@ -40,6 +40,10 @@ export type AgentEntryData = {
 	details: AgentCommandDetails;
 };
 
+export type DetachedEntryData = {
+	sessionId: string;
+};
+
 export type AgentResultMessage = {
 	customType: string;
 	content: string;
@@ -67,6 +71,8 @@ export type AgentCommandDetails = {
 
 export type RunningAgent = {
 	id: string;
+	/** The child's own Pi session, resumable with `/resume <sessionId>` after the agent is detached. */
+	sessionId: string;
 	command: AgentCommandName;
 	inheritedContext: boolean;
 	model: string;
@@ -106,6 +112,7 @@ export type RunningAgent = {
 
 export type CompletedAgent = {
 	id: string;
+	sessionId: string;
 	command: AgentCommandName;
 	modelLabel: string;
 	task: string;
@@ -123,6 +130,7 @@ export type CompletedAgent = {
 };
 
 export const MESSAGE_TYPE = "pi-user-agents";
+export const DETACHED_ENTRY_TYPE = "pi-user-agents-detached";
 export const WIDGET_KEY = "pi-user-agents";
 export const STEERING_LOG_PATH = `${tmpdir()}/pi-user-agents-steer.log`;
 

package/transcript.ts

@@ -6,6 +6,7 @@ import type {
 	AgentEntryData,
 	AgentMessage,
 	AgentResultMessage,
+	DetachedEntryData,
 	ExtensionAPI,
 	ExtensionCommandContext,
 	RunningAgent,
@@ -13,6 +14,7 @@ import type {
 } from "./shared.js";
 import {
 	contextLabel,
+	DETACHED_ENTRY_TYPE,
 	escapeAttribute,
 	extractTag,
 	formatMs,
@@ -212,6 +214,11 @@ export function registerUserAgentRenderer(pi: ExtensionAPI): void {
 					)
 				: undefined,
 	);
+	pi.registerEntryRenderer<DetachedEntryData>(DETACHED_ENTRY_TYPE, (entry, _state, theme) =>
+		entry.data
+			? new Text(theme.fg("dim", `Detached session ${entry.data.sessionId}`), 0, 0)
+			: undefined,
+	);
 }
 
 function liveAgentCard(

package/widget.ts

@@ -49,12 +49,13 @@ export class UserAgentWidget {
 	private active = false;
 	private selectedIndex = 0;
 	private viewerOpen = false;
-	private disposeConfirmationTarget: ViewableAgent | undefined;
+	private detachConfirmationTarget: ViewableAgent | undefined;
 	private readonly completedAgents: CompletedAgent[] = [];
 
 	constructor(
 		private readonly runningAgents: Set<RunningAgent>,
 		private readonly sendJoinedResult: (message: AgentResultMessage) => void,
+		private readonly announceDetached: (sessionId: string) => void,
 	) {}
 
 	setUI(ui: UIContext): void {
@@ -63,7 +64,7 @@ export class UserAgentWidget {
 		this.ui = ui;
 		this.widgetRegistered = false;
 		this.tui = undefined;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 		this.inputUnsub = ui.onTerminalInput((data) => this.handleKey(data));
 	}
 
@@ -74,6 +75,7 @@ export class UserAgentWidget {
 	): void {
 		this.completedAgents.push({
 			id: agent.id,
+			sessionId: agent.sessionId,
 			command: agent.command,
 			modelLabel: agent.modelLabel,
 			task: agent.task,
@@ -140,7 +142,7 @@ export class UserAgentWidget {
 		this.widgetRegistered = false;
 		this.tui = undefined;
 		this.active = false;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 	}
 
 	private clear(): void {
@@ -155,7 +157,7 @@ export class UserAgentWidget {
 		}
 		this.active = false;
 		this.selectedIndex = 0;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 	}
 
 	private runningAgentsForWidget(): RunningAgent[] {
@@ -199,13 +201,13 @@ export class UserAgentWidget {
 		}
 
 		if (matchesKey(data, "down")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			this.selectedIndex = Math.min(entries.length - 1, this.selectedIndex + 1);
 			this.update();
 			return { consume: true };
 		}
 		if (matchesKey(data, "up")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			if (this.selectedIndex === 0) {
 				this.deactivate();
 				return { consume: true };
@@ -225,17 +227,17 @@ export class UserAgentWidget {
 			selected?.kind === "running" &&
 			isLiveAgent(selected.agent)
 		) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			this.interruptRunning(selected.agent);
 			return { consume: true };
 		}
 		if (matchesKey(data, "enter")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			if (selected) this.openSelected(selected.agent);
 			return { consume: true };
 		}
-		if (matchesKey(data, "x") && selected) {
-			if (!this.confirmDispose(selected.agent)) return { consume: true };
+		if (matchesKey(data, "d") && selected) {
+			if (!this.confirmDetach(selected.agent)) return { consume: true };
 			if (selected.kind === "running") this.closeRunning(selected.agent);
 			else this.dismissCompleted(selected.agent);
 			return { consume: true };
@@ -245,12 +247,12 @@ export class UserAgentWidget {
 		return undefined;
 	}
 
-	private confirmDispose(target: ViewableAgent): boolean {
-		if (this.disposeConfirmationTarget === target) {
-			this.disposeConfirmationTarget = undefined;
+	private confirmDetach(target: ViewableAgent): boolean {
+		if (this.detachConfirmationTarget === target) {
+			this.detachConfirmationTarget = undefined;
 			return true;
 		}
-		this.disposeConfirmationTarget = target;
+		this.detachConfirmationTarget = target;
 		this.update();
 		return false;
 	}
@@ -258,7 +260,7 @@ export class UserAgentWidget {
 	private deactivate(): void {
 		this.active = false;
 		this.selectedIndex = 0;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 		this.update();
 	}
 
@@ -290,7 +292,7 @@ export class UserAgentWidget {
 							if (isRunningAgent(agent)) this.interruptRunning(agent);
 						},
 					),
-				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "70%" } },
+				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "85%" } },
 			)
 			.then(
 				(action) => this.onViewerClosed(agent, action),
@@ -298,10 +300,12 @@ export class UserAgentWidget {
 			);
 	}
 
+	/** Detaching ends the live session and leaves its session file on disk, untouched. */
 	private closeRunning(agent: RunningAgent): void {
 		agent.aborted = true;
 		void agent.session?.abort();
 		agent.retire?.();
+		this.announceDetached(agent.sessionId);
 		this.update();
 	}
 
@@ -368,12 +372,12 @@ export class UserAgentWidget {
 
 	private onViewerClosed(agent: ViewableAgent, action: AgentViewerAction): void {
 		this.viewerOpen = false;
-		if (action === "dispose" && isRunningAgent(agent) && this.runningAgents.has(agent)) {
+		if (action === "detach" && isRunningAgent(agent) && this.runningAgents.has(agent)) {
 			this.closeRunning(agent);
 			return;
 		}
 		const completedAgent = this.completedAgents.find((candidate) => candidate.id === agent.id);
-		if (action === "dispose" && completedAgent) this.removeCompleted(completedAgent);
+		if (action === "detach" && completedAgent) this.removeCompleted(completedAgent);
 		else this.update();
 	}
 
@@ -384,6 +388,7 @@ export class UserAgentWidget {
 	private removeCompleted(agent: CompletedAgent): void {
 		const index = this.completedAgents.indexOf(agent);
 		if (index >= 0) this.completedAgents.splice(index, 1);
+		this.announceDetached(agent.sessionId);
 		const total = this.entries().length;
 		if (total === 0) {
 			this.deactivate();
@@ -413,18 +418,18 @@ export class UserAgentWidget {
 			lines.push(truncateToWidth(`  ${theme.fg("dim", "←/↓ select agent")}`, width));
 		} else {
 			const selected = entries[this.selectedIndex];
-			const confirmingDispose = this.disposeConfirmationTarget === selected?.agent;
+			const confirmingDetach = this.detachConfirmationTarget === selected?.agent;
 			const segments = [theme.fg("accent", "↑↓ select"), theme.fg("accent", "Enter view")];
 			if (
-				!confirmingDispose &&
+				!confirmingDetach &&
 				selected?.kind === "running" &&
 				isLiveAgent(selected.agent)
 			)
 				segments.push(theme.fg("accent", "Ctrl+x interrupt"));
 			segments.push(
 				theme.fg(
-					confirmingDispose ? "error" : "accent",
-					confirmingDispose ? "x again to confirm" : "x dispose",
+					confirmingDetach ? "error" : "accent",
+					confirmingDetach ? "d again to confirm" : "d detach",
 				),
 				theme.fg("accent", "Esc back"),
 			);