@linxiraos/pi-tui 1.2.1 → 1.3.1

package/src/overlays/jobs-panel.ts

@@ -1,34 +1,22 @@
 /**
  * The async background jobs of a session as {@link JobsSheet}: the dismissable
- * sheet the native jobs pill and `/jobs` open. It draws task jobs as `agent`
- * nodes and the others as a status dot, the one-line label and a live
- * `elapsed`, lists every job and inspects the selected one (command, cwd, live
- * pids, exit code, output tail).
+ * sheet the native jobs pill and `/jobs` open. A master–detail split lists
+ * every job of the session's agent and its subagents as a tree (see
+ * {@link buildJobTree}) beside the selected one's status, command, facts
+ * (cwd, live pids, exit code, artifact) and live output.
  */
-import type { TspAgentProps, TspSpan } from "@linxiraos/pi-wire";
+import type { TspSpan, TspTone } from "@linxiraos/pi-wire";
 import { formatDuration } from "@linxiraos/pi-utils";
 import type { Component } from "../tui";
 import { matchesSelectCancel, matchesSelectDown, matchesSelectUp } from "../keybinding-matchers";
 import { matchesKey } from "../keys";
 import { truncateToWidth } from "../utils";
 import { collapseCommand } from "../apps/ps-data";
-import {
-	ansi,
-	card,
-	code,
-	col,
-	compact,
-	elapsed,
-	item,
-	kv,
-	node,
-	row,
-	span,
-	stableKey,
-	text,
-} from "../native/describe";
+import { ansi, code, col, compact, item, node, row, span, stableKey, text } from "../native/describe";
 import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
 import { actionBar, actionButton, selectList } from "../native/overlay";
+import { theme } from "../theme/theme";
+import { buildJobTree, type JobTreeAgent, type JobTreeRow, jobTreeGuide } from "./job-tree";
 
 /** One async job as the session snapshots it. */
 export interface JobsPanelJob {
@@ -38,14 +26,20 @@ export interface JobsPanelJob {
 	readonly label: string;
 	readonly startTime: number;
 	readonly endTime?: number;
+	/** Registry id of the agent that owns the job. */
+	readonly ownerId?: string;
 	/** Registry id of the subagent a task job runs. */
 	readonly agentId?: string;
 }
 
-/** Running and recently settled jobs. */
+/** Running and recently settled jobs of an agent and its subagents. */
 export interface JobsPanelSnapshot {
 	readonly running: readonly JobsPanelJob[];
 	readonly recent: readonly JobsPanelJob[];
+	/** The agent the sheet is for: its jobs sit at the top level, and only they can be cancelled. */
+	readonly rootId?: string;
+	/** Subagents owning listed jobs, with the ancestors linking them to the root. */
+	readonly agents?: readonly JobTreeAgent[];
 }
 
 /** What the sheet shows about the selected job beyond its row. */
@@ -68,37 +62,57 @@ export interface JobsSheetSource {
 	load(): JobsPanelSnapshot;
 	/** The selected job's detail; runs once per frame, undefined once the job is gone. */
 	inspect(id: string): JobsPanelDetail | undefined;
-	/** Cancel a running job. */
-	cancel(id: string): void;
+	/**
+	 * Cancel a running job. Omitted by a read-only sheet (a focused subagent
+	 * view, which only watches that agent): it lists the jobs and offers no way
+	 * to stop them.
+	 */
+	cancel?(id: string): void;
 	/** Dismiss the sheet. */
 	close(): void;
 }
 
-const AGENT_STATUS: Record<JobsPanelJob["status"], TspAgentProps["status"]> = {
-	running: "running",
-	completed: "done",
-	failed: "failed",
-	cancelled: "aborted",
+/** A job's status as the sheet names it. */
+const STATUS_LABEL: Record<JobsPanelJob["status"], string> = {
+	running: "Running",
+	completed: "Done",
+	failed: "Failed",
+	cancelled: "Cancelled",
 };
 
-const DOT: Record<JobsPanelJob["status"], TspSpan> = {
-	running: { t: "●", s: "accent", fx: "pulse" },
-	completed: { t: "●", s: "success" },
-	failed: { t: "●", s: "error" },
-	cancelled: { t: "●", s: "dim" },
+/** A job's status color: the list row's icon and the detail's status pill. */
+const STATUS_TONE: Record<JobsPanelJob["status"], TspTone> = {
+	running: "pending",
+	completed: "success",
+	failed: "error",
+	cancelled: "muted",
 };
 
+/** The status pill's lead glyph; a running job's pulses. */
+const STATUS_GLYPH: Record<JobsPanelJob["status"], TspSpan> = {
+	running: { t: "●", fx: "pulse" },
+	completed: { t: "✓" },
+	failed: { t: "✕" },
+	cancelled: { t: "⊘" },
+};
+
+/** The list row's icon per job type (Tern icon names); other types read as a generic job. */
+const TYPE_ICON: Record<string, string> = { bash: "bash", task: "agent" };
+
 /** Output tail rows the terminal fallback shows under the selected job. */
 const FALLBACK_TAIL_LINES = 8;
 
 /**
  * The jobs pill's sheet: a centred `lg` glass sheet titled Background jobs.
- * A selectable list of every job (running first) sits over the selected
- * job's detail: status and live elapsed (a task job's `agent` node), cwd,
- * live pids, exit code, the full command and a tail-following output pane.
- * It re-reads the session every frame, so the caller re-renders it on a
- * timer while it is open. ↑/↓ select, X cancels the selected running job,
- * Esc or Close dismisses; nothing enters the transcript.
+ * A master–detail split (it stacks in a narrow pane): the selectable job tree
+ * beside the selected job's detail — a status pill with live elapsed and
+ * Cancel job, its command or task, facts (agent, cwd, live pids, exit code,
+ * artifact) and a tail-following output pane. With no jobs it shows an empty
+ * state. It re-reads the session every frame, so the caller re-renders it on
+ * a timer while it is open. ↑/↓ select, X cancels the selected running job,
+ * Esc or Close dismisses; nothing enters the transcript. A source without
+ * `cancel` renders read-only, and a subagent's job never offers Cancel: only
+ * the root's own jobs can be stopped here.
  */
 export class JobsSheet implements Component {
 	readonly nativeOverlay = {
@@ -117,17 +131,20 @@ export class JobsSheet implements Component {
 		this.#source = source;
 	}
 
-	describe(cx: DescribeContext): NativeNode {
-		const agent = cx.supports("agent");
-		const { jobs, selected } = this.#current();
+	describe(_cx: DescribeContext): NativeNode {
+		const { rows, jobs, selected, cancellable } = this.#current();
 		const detail = selected && this.#source.inspect(selected.id);
 		const now = Date.now();
 		// Elapsed nodes tick on their own; list values and the output pane redraw
-		// when a job starts, settles or leaves, its process changes, its output
-		// grows, or (while one runs) once a second.
+		// when a job starts, settles, leaves or moves in the tree, its process
+		// changes, its output grows, or (while one runs) once a second.
 		const key = [
-			agent,
-			jobs.map(job => `${job.id}:${job.status}`).join(","),
+			rows
+				.map(
+					entry =>
+						`${jobTreeGuide(entry, theme)}${entry.kind === "job" ? `${entry.job.id}:${entry.job.status}` : entry.agent.id}`,
+				)
+				.join(","),
 			selected?.id,
 			detail?.pids.join(" "),
 			detail?.exitCode,
@@ -136,38 +153,47 @@ export class JobsSheet implements Component {
 		].join("|");
 		const output = detail?.output;
 		if (this.#native?.key === key && this.#native.output === output) return this.#native.node;
-		const actions = [null, actionButton("Close", "close", { keys: "escape" })];
-		if (selected?.status === "running") {
-			actions.unshift(actionButton("Cancel job", "cancel", { keys: "x", tone: "error" }));
-		}
-		const described = col(
-			compact([
-				selectList(
-					"jobs",
-					jobs.map(job => describeJobItem(job, now)),
-					{ selected: selected?.id ?? null, empty: "No background jobs", max: { lines: 6 } },
-				),
-				selected && describeDetail(selected, detail, now, agent),
-				actionBar(actions),
-			]),
-			{ gap: "md" },
-		);
+		const close = actionButton("Close", "close", { keys: "escape" });
+		const described = selected
+			? col([
+					node(
+						"row",
+						{ role: "zeta.jobs.split" },
+						[
+							node("col", { role: "zeta.jobs.master" }, [describeJobList(rows, selected, now)], "master"),
+							describeDetail(selected, detail, now, cancellable),
+						],
+						"split",
+					),
+					actionBar([describeSummary(jobs), null, close]),
+				])
+			: col([describeEmpty(), actionBar([null, close])]);
 		this.#native = { key, output, node: described };
 		return described;
 	}
 
-	/** Rows for a terminal without the native surface: one per job, then the selected job's facts and output tail. */
+	/** Rows for a terminal without the native surface: the job tree, then the selected job's facts and output tail. */
 	render(width: number): readonly string[] {
-		const { jobs, selected } = this.#current();
+		const { rows, jobs, selected } = this.#current();
 		const now = Date.now();
 		const running = jobs.filter(job => job.status === "running").length;
 		const lines = [truncateToWidth(` Background jobs · ${running} running`, width)];
 		if (jobs.length === 0) lines.push(" No background jobs");
-		for (const job of jobs) {
+		for (const entry of rows) {
+			const guide = jobTreeGuide(entry, theme);
+			if (entry.kind === "agent") {
+				lines.push(truncateToWidth(`  ${guide}${entry.agent.id}`, width));
+				continue;
+			}
+			const { job } = entry;
 			const cursor = job === selected ? ">" : " ";
 			const age = formatDuration(jobAge(job, now));
+			const agent = entry.agent && entry.agent.id !== job.label ? `${entry.agent.id}: ` : "";
 			lines.push(
-				truncateToWidth(`${cursor} ${job.status}  ${job.type} ${age}  ${collapseCommand(job.label)}`, width),
+				truncateToWidth(
+					`${cursor} ${guide}${job.status}  ${job.type} ${age}  ${agent}${collapseCommand(job.label)}`,
+					width,
+				),
 			);
 		}
 		const detail = selected && this.#source.inspect(selected.id);
@@ -204,13 +230,24 @@ export class JobsSheet implements Component {
 		else if (event.type === "action" && event.act === "cancel") this.#cancelSelected();
 	}
 
-	/** Every job, running first, and the selected one (the first when the selection left). */
-	#current(): { jobs: readonly JobsPanelJob[]; selected: JobsPanelJob | undefined } {
-		const { running, recent } = this.#source.load();
-		const jobs = [...running, ...recent];
+	/**
+	 * The job tree, its jobs in tree order, the selected one (the first when
+	 * the selection left) and whether the sheet can stop it: a job the root
+	 * owns, with a source that cancels.
+	 */
+	#current(): {
+		rows: readonly JobTreeRow<JobsPanelJob>[];
+		jobs: readonly JobsPanelJob[];
+		selected: JobsPanelJob | undefined;
+		cancellable: boolean;
+	} {
+		const { running, recent, rootId, agents } = this.#source.load();
+		const rows = buildJobTree([...running, ...recent], agents ?? [], rootId);
+		const jobs = rows.flatMap(entry => (entry.kind === "job" ? [entry.job] : []));
 		const selected = jobs.find(job => job.id === this.#selectedId) ?? jobs[0];
 		this.#selectedId = selected?.id;
-		return { jobs, selected };
+		const owned = selected?.ownerId === undefined || selected.ownerId === rootId;
+		return { rows, jobs, selected, cancellable: this.#source.cancel !== undefined && owned };
 	}
 
 	#tailLines(id: string, output: string): readonly string[] {
@@ -229,8 +266,8 @@ export class JobsSheet implements Component {
 	}
 
 	#cancelSelected(): void {
-		const { selected } = this.#current();
-		if (selected?.status === "running") this.#source.cancel(selected.id);
+		const { selected, cancellable } = this.#current();
+		if (cancellable && selected?.status === "running") this.#source.cancel?.(selected.id);
 	}
 }
 
@@ -256,94 +293,137 @@ function tailLines(text: string, count: number): string[] {
 	return lines.reverse();
 }
 
-/** A task job as an `agent` node when the terminal draws them, else a one-line dot row. */
-function describeJob(job: JobsPanelJob, nowMs: number, agent: boolean): NativeNode {
-	const settled = job.status !== "running";
-	const age = jobAge(job, nowMs);
-	if (agent && job.type === "task") {
+/**
+ * The master list: the job tree, connectors leading each label. A subagent
+ * without a listed task job heads its jobs as a quiet label (a plain text
+ * child: no row behavior, so ↑/↓ and clicks pass it by).
+ */
+function describeJobList(rows: readonly JobTreeRow<JobsPanelJob>[], selected: JobsPanelJob, nowMs: number): NativeNode {
+	const children: NativeChild[] = rows.map(entry => {
+		const guide = jobTreeGuide(entry, theme);
+		if (entry.kind === "job") return describeJobItem(entry.job, entry.agent?.id, guide, nowMs);
 		return node(
-			"agent",
+			"text",
 			{
-				name: job.agentId ?? job.id,
-				agent: "task",
-				task: job.label,
-				status: AGENT_STATUS[job.status],
-				stats: settled ? { took: age } : { age },
+				role: "zeta.jobs.group",
+				spans: compact([guide !== "" && span(guide, "mono dim"), span(entry.agent.id)]),
+				wrap: "none",
 			},
 			undefined,
-			job.id,
+			`agent-${stableKey(entry.agent.id)}`,
 		);
-	}
-	return node(
-		"row",
-		{ role: "zeta.jobs.row", gap: "sm", align: "center", title: `${job.id} · ${job.type} · ${job.status}` },
-		[
-			text([DOT[job.status]], { aria: job.status, shrink: 0 }),
-			text([span(collapseCommand(job.label))], { wrap: "none", truncate: "end", grow: 1 }),
-			text([span(job.type, "dim")], { wrap: "none", shrink: 0 }),
-			elapsed(age, settled),
-		],
-		job.id,
-	);
+	});
+	return selectList("jobs", children, { selected: selected.id, max: { lines: 12 } });
 }
 
-/** One sheet list row: status dot and one-line label, then type and age. */
-function describeJobItem(job: JobsPanelJob, nowMs: number): NativeNode {
+/**
+ * One list row: the type icon tinted by status, the tree connector, the
+ * subagent a task job runs, the one-line label (a process job's command in
+ * mono, a task's work in prose) and how long it ran.
+ */
+function describeJobItem(job: JobsPanelJob, agentName: string | undefined, guide: string, nowMs: number): NativeNode {
+	const status = STATUS_LABEL[job.status];
+	const age = formatDuration(jobAge(job, nowMs));
 	return item(job.id, {
-		label: [DOT[job.status], span(" "), span(collapseCommand(job.label))],
-		value: [span(job.type, "dim"), span(` · ${formatDuration(jobAge(job, nowMs))}`, "muted")],
-		title: `${job.id} · ${job.type} · ${job.status}`,
+		label: compact([
+			guide !== "" && span(guide, "mono dim"),
+			agentName !== undefined && agentName !== job.label && span(`${agentName} `, "strong"),
+			job.type === "task" ? span(job.label) : span(collapseCommand(job.label), "mono"),
+		]),
+		value: [span(age, "mono")],
+		icon: TYPE_ICON[job.type] ?? "job",
+		tone: STATUS_TONE[job.status],
+		title: `${job.label}\n${status} · ${job.type} · ${job.id}`,
+		aria: `${job.label}, ${status.toLowerCase()}, ${age}`,
 	});
 }
 
-/** The selected job: status line (or `agent` node), facts, command and output tail. */
+/** The footer's at-a-glance count. */
+function describeSummary(jobs: readonly JobsPanelJob[]): NativeNode {
+	const running = jobs.filter(job => job.status === "running").length;
+	const parts = compact([
+		running > 0 && `${running} running`,
+		jobs.length > running && `${jobs.length - running} recent`,
+	]);
+	return node("text", { role: "zeta.jobs.summary", text: parts.join(" · "), wrap: "none" }, undefined, "summary");
+}
+
+/** No jobs: what the sheet is for, in place of the split. */
+function describeEmpty(): NativeNode {
+	return node(
+		"col",
+		{ role: "zeta.jobs.empty", align: "center" },
+		[
+			node("icon", { name: "jobs" }),
+			text("No background jobs", { role: "zeta.jobs.empty.title" }),
+			text("Commands and subagent tasks started in the background show up here while they run.", {
+				role: "zeta.jobs.empty.note",
+				wrap: "word",
+			}),
+		],
+		"empty",
+	);
+}
+
+/**
+ * The selected job: a status line (pill, live elapsed, type · id, Cancel job
+ * when `cancellable`), its task or full command, facts and the output pane (or
+ * its empty state).
+ */
 function describeDetail(
 	job: JobsPanelJob,
 	detail: JobsPanelDetail | undefined,
 	nowMs: number,
-	agent: boolean,
+	cancellable: boolean,
 ): NativeNode {
 	const settled = job.status !== "running";
 	const exit = detail?.exitCode;
+	const age = Math.round(jobAge(job, nowMs));
+	const command = detail?.command ?? (job.type === "task" ? undefined : job.label);
+	const pids = detail?.pids ?? [];
+	const facts = compact([
+		job.agentId ? { k: "Agent", v: [span(job.agentId, "mono")] } : undefined,
+		detail?.cwd ? { k: "Directory", v: [span(detail.cwd, "path")] } : undefined,
+		pids.length > 0 && { k: pids.length > 1 ? "PIDs" : "PID", v: [span(pids.join(", "), "num")] },
+		exit !== undefined && { k: "Exit code", v: [span(String(exit), exit === 0 ? "success" : "error")] },
+		detail?.artifactId ? { k: "Full output", v: [span(`artifact://${detail.artifactId}`, "mono")] } : undefined,
+	]);
 	const children = compact<NativeChild>([
-		agent && job.type === "task"
-			? describeJob(job, nowMs, agent)
-			: row(
-					[
-						text(
-							[DOT[job.status], span(` ${job.status}`, "strong"), span(` · ${job.type} · ${job.id}`, "muted")],
-							{
-								wrap: "none",
-								truncate: "end",
-							},
-						),
-						elapsed(jobAge(job, nowMs), settled),
-					],
-					{ gap: "sm", align: "center" },
-				),
-		detail &&
-			kv([
-				["Directory", detail.cwd && [span(detail.cwd, "path")]],
-				["PID", detail.pids.length > 0 ? [span(detail.pids.join(", "), "num")] : undefined],
-				["Exit", exit === undefined ? undefined : [span(String(exit), exit === 0 ? "success" : "error")]],
-				["Full output", detail.artifactId && [span(`artifact://${detail.artifactId}`, "mono")]],
+		row(
+			compact<NativeChild>([
+				text([STATUS_GLYPH[job.status], span(` ${STATUS_LABEL[job.status]}`)], {
+					role: "zeta.jobs.state",
+					tone: STATUS_TONE[job.status],
+					wrap: "none",
+				}),
+				node("elapsed", {
+					age,
+					...(settled ? { stopped: age } : {}),
+					format: "short",
+					role: "zeta.jobs.age",
+					title: settled ? "Ran for" : "Running for",
+				}),
+				text([span(`${job.type} · ${job.id}`, "mono")], { role: "zeta.jobs.id", wrap: "none", truncate: "end" }),
+				node("spacer", { grow: 1 }),
+				cancellable && !settled && actionButton("Cancel job", "cancel", { keys: "x", tone: "error" }),
 			]),
-		// The row shows the command on one line; show it whole when that cut or collapsed it.
-		detail?.command && detail.command !== collapseCommand(job.label)
-			? card(
-					{
-						head: [span("Command", "muted")],
-						variant: "bare",
-						collapsible: true,
-						collapsed: true,
-						preview: { lines: 3 },
-					},
-					[code(detail.command, { lang: "bash", wrap: true })],
-				)
-			: undefined,
-		detail?.output
-			? ansi(detail.output, { follow: !settled, role: "zeta.jobs.output", max: { h: "16lines" } })
-			: text([span(settled ? "No output" : "No output yet", "dim")]),
+			{ role: "zeta.jobs.status", gap: "sm", align: "center" },
+		),
+		command
+			? code(command, { lang: "bash", wrap: true, preview: { lines: 4 }, role: "zeta.jobs.command" })
+			: text(job.label, { role: "zeta.jobs.title", wrap: "word" }),
+		facts.length > 0 && node("kv", { items: facts, role: "zeta.jobs.facts" }),
+		node(
+			"col",
+			{ role: "zeta.jobs.out", gap: "sm" },
+			[
+				text("Output", { role: "zeta.jobs.label" }),
+				detail?.output
+					? ansi(detail.output, { follow: !settled, role: "zeta.jobs.output", max: { h: "16lines" } })
+					: text(settled ? "No output" : "No output yet", { role: "zeta.jobs.nooutput" }),
+			],
+			"out",
+		),
 	]);
-	return node("col", { gap: "sm", role: "zeta.jobs.detail" }, children, stableKey(job.id));
+	return node("col", { role: "zeta.jobs.detail" }, children, stableKey(job.id));
 }