pi-agent-squad 0.8.4 → 0.9.0

package/README.md

@@ -64,6 +64,8 @@ metadata and does not sandbox filesystem access.
 ## Features
 
 - **Delegation**: `subagent` tool (sync / background `async:true`); background results are injected into the main session when done.
+- **Durable background ledger**: key background lifecycle snapshots are stored as TUI-only custom entries on the current Pi session branch.
+- **Recovery and explicit retry**: reopening a session restores background history, marks stale work interrupted, repairs pending result delivery, and supports `/subagent-retry <runId>` without automatically rerunning old work.
 - **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + an active-run registry that covers both direct runs and resident RPC processes.
 - **Non-blocking**: background tasks do not occupy the main session.
 - **Adaptive orchestration is opt-in**: `/orchestrate on` enables main's discretion to delegate based on speed, quality, context management, independent judgment, and parallel progress while weighing latency, over-analysis, misunderstanding, duplication, and integration risk.
@@ -100,7 +102,10 @@ The TUI-only widget is installed above the editor while at least one subagent is
   the hint and hide it when the title itself needs the space.
 - The elapsed time and spinner refresh once per second while work is active, avoiding hot-loop rerenders on very large sessions.
 - Normal completion, failure, timeout, cancellation, crash, and session shutdown all remove the matching activity. The widget itself is removed when no activities remain.
-- JSON/RPC/print modes do not install the widget.
+- JSON/RPC/print modes do not install the widget. In RPC mode the same live runs
+  are instead published as the `cypher.subagents.v1` status snapshot (see
+  `cypher-status.ts`), which is what a GUI host such as Cypher renders in its
+  Subagents panel.
 
 ### Keyboard navigation
 
@@ -178,6 +183,39 @@ from the visible transcript:
   `triggerTurn: true` and `deliverAs: "steer"`, preserving the former
   synthetic-user-message behavior without inheriting `userMessageBg`.
 
+## Background task persistence and recovery
+
+Background task lifecycle state is append-only in the current Pi session. The
+plugin writes `agent-squad-task-state` snapshots for `starting`, `running`,
+`completed`, `failed`, `cancelled`, and `interrupted` transitions. These custom
+entries do not enter LLM context.
+
+When the same session is reopened, the plugin reconstructs the ledger from the
+**active branch**. The last valid snapshot for each run is authoritative.
+Malformed entries and unknown schema versions are ignored independently.
+
+- A `starting` or `running` task owned by an older plugin runtime is changed to
+  `interrupted`; it is never assumed alive from a PID or child-session path.
+- Interrupted, failed, and cancelled work is **not** automatically rerun. Use
+  `/subagent-retry <runId>` to create a new background run with a new run ID and
+  address. The new ledger entry records `retryOf`.
+- Completion is persisted before its result is injected. If a completed result
+  was not delivered before shutdown, reopening the session schedules recovery
+  delivery after session initialization.
+- Each completed result uses `agent-squad-result:<runId>` as its stable
+  `deliveryId`. Recovery scans durable custom-message entries for that ID before
+  sending and again immediately before delivery, preventing duplicate result
+  messages across crash windows.
+- `/subagent-status` merges current live tasks with bounded current-branch
+  history and distinguishes delivered from pending completed results.
+
+The ledger stores bounded metadata and result/error summaries, not complete
+child transcripts, credentials, controllers, promises, streams, or callbacks.
+Background child Pi sessions remain separate and retain their full transcript;
+the ledger stores only the bounded summary plus the child session file path.
+This version does **not** revive dead OS processes, take over processes from an
+older runtime, daemonize subagents, or provide cross-runtime process keepalive.
+
 ## Architecture
 
 ```
@@ -210,6 +248,11 @@ subagents/
 |-- message.ts      # generic messaging (file channel + send/reply/read + main-side router)
 |-- session.ts      # common interactive session-handle interface
 |-- session-ui.ts   # focused overlay for live transcript + interactive input
+|-- cypher-status.ts # `cypher.subagents.v1` live run projection for GUI hosts (RPC mode)
+|-- task-state.ts   # durable schema, validation, and branch reconstruction
+|-- task-recovery.ts # stale-run and undelivered-result reconciliation planning
+|-- task-delivery.ts # delivery IDs, durable dedupe, and recovery outbox
+|-- task-status.ts  # bounded live + persisted status formatting
 |-- orchestrator.md # main-agent adaptive delegation prompt (enabled with /orchestrate on)
 `-- README.md
 ```
@@ -230,6 +273,9 @@ pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 "Use subagent async=true, agent=actor, task=..."     # explicit background delegation
 "Use subagent agent=reviewer timeoutSeconds=120 ..." # override the default 6h task timeout (only when the user asked)
 "Have reviewer review the recent changes"            # main agent delegates to reviewer
+
+/subagent-status                 # live tasks plus bounded current-branch history
+/subagent-retry <full-run-id>    # explicit retry; creates a new run id/address
 ```
 
 Main is not required to follow a fixed planner → actor → reviewer chain. It may

package/cypher-status.ts

@@ -0,0 +1,401 @@
+/**
+ * Cypher subagent status protocol (`cypher.subagents.v1`).
+ *
+ * Cypher runs Pi in RPC mode and has no terminal to render the TUI widget
+ * into. Instead it consumes a STRUCTURED live projection published through
+ * `ctx.ui.setStatus`: the one status key Cypher parses instead of treating as
+ * transient TUI furniture. Without it a subagent run shows as an eternal
+ * "starting" row in Cypher's Subagents inspector, because the only other
+ * signal it has is an unresolved tool call.
+ *
+ * Contract (mirrors Cypher's `parse_subagent_status`, which validates every
+ * field strictly and DROPS THE WHOLE SNAPSHOT on any violation):
+ * - key `cypher.subagents.v1`, value `JSON.stringify({version: 1, runs: […]})`;
+ *   blank text is a CLEAR snapshot.
+ * - per run: `runId` + `agent` + `mode` (`sync|async|message`) + `status`
+ *   (`running|done|error`) + `startedAt`/`updatedAt` epoch millis are
+ *   required; `toolCallId`, `model`, `task`, `progress`, `endedAt` optional.
+ * - bounds: ≤32 runs, task ≤500 chars, progress ≤8 lines / 4KiB, snapshot
+ *   ≤64KiB.
+ *
+ * `updatedAt` doubles as the heartbeat: Cypher greys a run out as stale after
+ * 45s of silence, so live runs are republished on a timer.
+ *
+ * RPC mode only — the TUI keeps its own widget and must never be handed this
+ * JSON. A standalone Pi (no Cypher) simply never attaches.
+ */
+
+export const CYPHER_SUBAGENT_STATUS_KEY = "cypher.subagents.v1";
+
+const SNAPSHOT_VERSION = 1;
+/** Snapshot bounds — Cypher re-checks each one and ignores a snapshot that breaks any. */
+const MAX_RUNS = 32;
+const MAX_TASK_CHARS = 500;
+const MAX_PROGRESS_LINES = 8;
+const MAX_PROGRESS_BYTES = 4096;
+const MAX_SNAPSHOT_BYTES = 64 * 1024;
+/** Settled runs kept in the snapshot so the panel can show Done/Error instead of a row that vanishes. */
+const MAX_TERMINAL_RUNS = 8;
+/** Progress tail kept per run (Cypher renders the last line on the row). */
+const MAX_PROGRESS_KEPT = 6;
+const MAX_PROGRESS_LINE_CHARS = 160;
+/** Republish period for live runs; Cypher's staleness window is 45s. */
+const HEARTBEAT_MS = 10_000;
+/**
+ * Floor between progress-driven publishes. Every snapshot Cypher accepts is a
+ * synced session-row write, and a busy child emits tool events several times a
+ * second — lifecycle changes publish immediately, chatter coalesces.
+ */
+const MIN_PUBLISH_INTERVAL_MS = 750;
+
+export type CypherRunMode = "sync" | "async" | "message";
+export type CypherRunStatus = "running" | "done" | "error";
+
+/** One run as published. Field names are the wire format — camelCase, epoch millis. */
+export interface CypherRun {
+	runId: string;
+	toolCallId?: string;
+	agent: string;
+	model?: string;
+	task: string;
+	mode: CypherRunMode;
+	status: CypherRunStatus;
+	progress?: string;
+	startedAt: number;
+	updatedAt: number;
+	endedAt?: number;
+}
+
+export interface CypherStatusSnapshot {
+	version: number;
+	runs: CypherRun[];
+}
+
+export interface StartRunInput {
+	runId: string;
+	agent: string;
+	task: string;
+	mode: CypherRunMode;
+	/** The parent tool call this run answers to (sync/async); absent for message activity. */
+	toolCallId?: string;
+	model?: string;
+	startedAt?: number;
+}
+
+interface StatusUi {
+	setStatus(key: string, text: string | undefined): void;
+}
+
+interface StatusContext {
+	mode?: string;
+	ui?: Partial<StatusUi>;
+}
+
+function boundText(value: string, maxChars: number): string {
+	const text = String(value ?? "").replace(/\s+/g, " ").trim();
+	if (text.length <= maxChars) return text;
+	// Cut on a code point boundary: Cypher counts characters, not UTF-16 units.
+	return `${[...text].slice(0, Math.max(0, maxChars - 1)).join("")}…`;
+}
+
+function boundLine(value: string): string {
+	const stripped = String(value ?? "").replace(/\u001b\[[0-9;]*[A-Za-z]/g, "");
+	return boundText(stripped, MAX_PROGRESS_LINE_CHARS);
+}
+
+/** Join the kept tail within BOTH Cypher's line and byte caps. */
+function renderProgress(lines: string[]): string | undefined {
+	let kept = lines.filter((line) => line.length > 0).slice(-MAX_PROGRESS_LINES);
+	while (kept.length > 0 && Buffer.byteLength(kept.join("\n"), "utf8") > MAX_PROGRESS_BYTES) {
+		kept = kept.slice(1);
+	}
+	const text = kept.join("\n");
+	return text.length > 0 ? text : undefined;
+}
+
+/** A short, human-readable argument for a child tool call ("bash: cargo test"). */
+function summarizeToolArgs(args: unknown): string {
+	if (!args || typeof args !== "object") return "";
+	const record = args as Record<string, unknown>;
+	for (const key of ["command", "path", "file_path", "pattern", "query", "url"]) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) return boundText(value, 60);
+	}
+	return "";
+}
+
+/** First meaningful line of an assistant message's text content. */
+function assistantHeadline(message: any): string {
+	const content = message?.content;
+	const parts = Array.isArray(content) ? content : [];
+	for (const part of parts) {
+		const text = typeof part?.text === "string" ? part.text : "";
+		const line = text.split("\n").map((l: string) => l.trim()).find((l: string) => l.length > 0);
+		if (line) return boundLine(line);
+	}
+	if (typeof content === "string") {
+		const line = content.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+		if (line) return boundLine(line);
+	}
+	return "";
+}
+
+/**
+ * The live run ledger Cypher reads. Deliberately independent of the TUI
+ * widget: the widget is presentation for a terminal, this is a protocol.
+ */
+export class CypherStatusPublisher {
+	private runs = new Map<string, CypherRun>();
+	private progress = new Map<string, string[]>();
+	private ui: StatusUi | undefined;
+	private timer: ReturnType<typeof setInterval> | undefined;
+	private pending: ReturnType<typeof setTimeout> | undefined;
+	private lastPublishAt = 0;
+	/** Last published text — an unchanged snapshot is never re-sent. */
+	private lastPublished: string | undefined;
+
+	/** RPC mode only. Re-attaching (a new session) keeps whatever is live. */
+	attach(ctx: StatusContext | undefined): void {
+		const ui = ctx?.mode === "rpc" ? ctx.ui : undefined;
+		this.ui = typeof ui?.setStatus === "function" ? (ui as StatusUi) : undefined;
+		this.lastPublished = undefined;
+		if (!this.ui) {
+			this.stopHeartbeat();
+			return;
+		}
+		if (this.liveCount() > 0) this.startHeartbeat();
+		this.publish(true);
+	}
+
+	/** Session shutdown: clear the board so Cypher never keeps a ghost runner. */
+	shutdown(): void {
+		this.runs.clear();
+		this.progress.clear();
+		this.stopHeartbeat();
+		this.cancelPending();
+		if (this.ui) {
+			this.ui.setStatus(CYPHER_SUBAGENT_STATUS_KEY, undefined);
+			this.lastPublished = undefined;
+		}
+		this.ui = undefined;
+	}
+
+	get size(): number {
+		return this.runs.size;
+	}
+
+	/** Is this run still published as running? */
+	isLive(runId: string): boolean {
+		return this.runs.get(runId)?.status === "running";
+	}
+
+	/** Snapshot the publisher would send right now (the unit-test surface). */
+	snapshot(): CypherStatusSnapshot {
+		return { version: SNAPSHOT_VERSION, runs: this.orderedRuns() };
+	}
+
+	start(input: StartRunInput): void {
+		const now = Date.now();
+		const startedAt = input.startedAt ?? now;
+		this.runs.set(input.runId, {
+			runId: input.runId,
+			...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
+			agent: boundText(input.agent, 120) || "subagent",
+			...(input.model ? { model: boundText(input.model, 120) } : {}),
+			task: boundText(input.task, MAX_TASK_CHARS),
+			mode: input.mode,
+			status: "running",
+			startedAt,
+			updatedAt: now,
+		});
+		this.progress.delete(input.runId);
+		this.startHeartbeat();
+		this.publish(true);
+	}
+
+	/** Model discovered mid-run, or a new progress line. No-op for unknown runs. */
+	update(runId: string, patch: { model?: string; progressLine?: string }): void {
+		const run = this.runs.get(runId);
+		if (!run || run.status !== "running") return;
+		let changed = false;
+		if (patch.model && !run.model) {
+			run.model = boundText(patch.model, 120);
+			changed = true;
+		}
+		const line = patch.progressLine ? boundLine(patch.progressLine) : "";
+		if (line) {
+			const lines = this.progress.get(runId) ?? [];
+			// Consecutive duplicates are noise (a tool retried on every chunk).
+			if (lines[lines.length - 1] !== line) {
+				lines.push(line);
+				this.progress.set(runId, lines.slice(-MAX_PROGRESS_KEPT));
+				changed = true;
+			}
+		}
+		if (!changed) return;
+		run.updatedAt = Date.now();
+		this.publish();
+	}
+
+	/**
+	 * Terminalize a run only if it is still live — a teardown path that can run
+	 * after a specific `finish` (or after the owner lost interest) must never
+	 * leave a runner published forever.
+	 */
+	settleIfLive(runId: string, status: Exclude<CypherRunStatus, "running">, detail?: string): void {
+		if (!this.isLive(runId)) return;
+		this.finish(runId, status, detail);
+	}
+
+	finish(runId: string, status: Exclude<CypherRunStatus, "running">, detail?: string): void {
+		const run = this.runs.get(runId);
+		if (!run) return;
+		const now = Date.now();
+		run.status = status;
+		run.updatedAt = now;
+		run.endedAt = now;
+		const line = detail ? boundLine(detail) : "";
+		if (line) {
+			const lines = this.progress.get(runId) ?? [];
+			lines.push(line);
+			this.progress.set(runId, lines.slice(-MAX_PROGRESS_KEPT));
+		}
+		this.trimTerminal();
+		if (this.liveCount() === 0) this.stopHeartbeat();
+		this.publish(true);
+	}
+
+	/**
+	 * Child Pi RPC events → model + a progress tail. Best effort: the run is
+	 * still reported without any of this.
+	 */
+	observeChildEvent(runId: string, event: any): void {
+		if (!this.runs.has(runId)) return;
+		// This runs inside the child's event dispatch, which does NOT guard its
+		// callbacks: a throw here would break the run itself.
+		try {
+			const type = event?.type;
+			if (type === "tool_execution_start") {
+				const name = String(event?.toolName ?? "tool");
+				const args = summarizeToolArgs(event?.args);
+				this.update(runId, { progressLine: args ? `${name}: ${args}` : name });
+				return;
+			}
+			if (type === "message_end" && event?.message?.role === "assistant") {
+				const model = typeof event.message.model === "string" ? event.message.model : undefined;
+				this.update(runId, { model, progressLine: assistantHeadline(event.message) });
+			}
+		} catch {
+			/* a malformed child event is never worth a failed run */
+		}
+	}
+
+	private liveCount(): number {
+		let live = 0;
+		for (const run of this.runs.values()) if (run.status === "running") live++;
+		return live;
+	}
+
+	/** Live first (oldest first), then the most recently settled. */
+	private orderedRuns(): CypherRun[] {
+		const all = [...this.runs.values()];
+		const live = all.filter((run) => run.status === "running").sort((a, b) => a.startedAt - b.startedAt);
+		const settled = all
+			.filter((run) => run.status !== "running")
+			.sort((a, b) => (b.endedAt ?? b.updatedAt) - (a.endedAt ?? a.updatedAt));
+		return [...live, ...settled].slice(0, MAX_RUNS).map((run) => {
+			const progress = renderProgress(this.progress.get(run.runId) ?? []);
+			return progress ? { ...run, progress } : { ...run };
+		});
+	}
+
+	/** Keep the settled tail bounded so a long session never grows the board. */
+	private trimTerminal(): void {
+		const settled = [...this.runs.values()]
+			.filter((run) => run.status !== "running")
+			.sort((a, b) => (b.endedAt ?? b.updatedAt) - (a.endedAt ?? a.updatedAt));
+		for (const run of settled.slice(MAX_TERMINAL_RUNS)) {
+			this.runs.delete(run.runId);
+			this.progress.delete(run.runId);
+		}
+	}
+
+	private startHeartbeat(): void {
+		// Nothing consumes the snapshot outside Cypher, so a standalone TUI must
+		// not even carry the timer.
+		if (!this.ui || this.timer) return;
+		this.timer = setInterval(() => {
+			if (this.liveCount() === 0) {
+				this.stopHeartbeat();
+				return;
+			}
+			const now = Date.now();
+			for (const run of this.runs.values()) if (run.status === "running") run.updatedAt = now;
+			this.publish(true);
+		}, HEARTBEAT_MS);
+		// A heartbeat must never hold the process open.
+		this.timer.unref?.();
+	}
+
+	private stopHeartbeat(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+
+	/** `immediate` = a lifecycle change; anything else coalesces. */
+	private publish(immediate = false): void {
+		if (!this.ui) return;
+		const waited = Date.now() - this.lastPublishAt;
+		if (!immediate && waited < MIN_PUBLISH_INTERVAL_MS) {
+			if (this.pending) return;
+			this.pending = setTimeout(() => {
+				this.pending = undefined;
+				this.publishNow();
+			}, MIN_PUBLISH_INTERVAL_MS - waited);
+			this.pending.unref?.();
+			return;
+		}
+		this.cancelPending();
+		this.publishNow();
+	}
+
+	private publishNow(): void {
+		if (!this.ui) return;
+		const text = serializeSnapshot(this.orderedRuns());
+		this.lastPublishAt = Date.now();
+		if (text === this.lastPublished) return;
+		this.lastPublished = text;
+		try {
+			this.ui.setStatus(CYPHER_SUBAGENT_STATUS_KEY, text);
+		} catch {
+			/* a status frame must never break a run */
+		}
+	}
+
+	private cancelPending(): void {
+		if (!this.pending) return;
+		clearTimeout(this.pending);
+		this.pending = undefined;
+	}
+}
+
+/**
+ * Serialize within the 64KiB cap. Over budget, progress goes first, then the
+ * settled tail — the live runs are the part Cypher cannot re-derive.
+ */
+export function serializeSnapshot(runs: CypherRun[]): string {
+	const encode = (list: CypherRun[]) => JSON.stringify({ version: SNAPSHOT_VERSION, runs: list });
+	let text = encode(runs);
+	if (Buffer.byteLength(text, "utf8") <= MAX_SNAPSHOT_BYTES) return text;
+	const withoutProgress = runs.map(({ progress: _progress, ...run }) => run as CypherRun);
+	text = encode(withoutProgress);
+	if (Buffer.byteLength(text, "utf8") <= MAX_SNAPSHOT_BYTES) return text;
+	let live = withoutProgress.filter((run) => run.status === "running");
+	text = encode(live);
+	while (live.length > 1 && Buffer.byteLength(text, "utf8") > MAX_SNAPSHOT_BYTES) {
+		live = live.slice(0, Math.floor(live.length / 2));
+		text = encode(live);
+	}
+	return text;
+}