@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/modes/bridge/bridge-ui-context.ts

@@ -0,0 +1,200 @@
+import type {
+	ExtensionUIContext,
+	ExtensionUIDialogOptions,
+	ExtensionWidgetContent,
+	ExtensionWidgetOptions,
+	TerminalInputHandler,
+} from "../../extensibility/extensions";
+import type { UiRequestBroker, UiRequestCancelled, UiRequestResolution } from "../shared/agent-wire/ui-request-broker";
+import type { BridgeUiResult } from "../shared/agent-wire/ui-result";
+import { isUiUnsupported, isUiValue } from "../shared/agent-wire/ui-result";
+import { type Theme, theme } from "../theme/theme";
+
+export type BridgeUiRequestPayload =
+	| { kind: "select"; title: string; options: string[]; timeout?: number }
+	| { kind: "confirm"; title: string; message: string; timeout?: number }
+	| { kind: "input"; title: string; placeholder?: string; timeout?: number }
+	| { kind: "editor"; title: string; prefill?: string; promptStyle?: boolean }
+	| { kind: "notify"; message: string; type?: "info" | "warning" | "error" }
+	| { kind: "status"; key: string; text: string | undefined }
+	| { kind: "widget"; key: string; lines: string[] | undefined; placement?: "aboveEditor" | "belowEditor" }
+	| { kind: "title"; title: string }
+	| { kind: "set_editor_text"; text: string }
+	| { kind: "unsupported"; capability: string; reason: string };
+
+export type BridgeUiBroker = UiRequestBroker<BridgeUiRequestPayload, BridgeUiResult<unknown>>;
+export type BridgeUiEmitter = (payload: BridgeUiRequestPayload) => void;
+
+function isBrokerCancelled(resolution: UiRequestResolution<BridgeUiResult<unknown>>): resolution is UiRequestCancelled {
+	return resolution.status === "cancelled";
+}
+
+function timeoutFor(dialogOptions: ExtensionUIDialogOptions | undefined): number | undefined {
+	return dialogOptions?.timeout;
+}
+
+export class BridgeExtensionUIContext implements ExtensionUIContext {
+	readonly #broker: BridgeUiBroker;
+	readonly #emit: BridgeUiEmitter;
+
+	constructor(options: { broker: BridgeUiBroker; emit: BridgeUiEmitter }) {
+		this.#broker = options.broker;
+		this.#emit = options.emit;
+	}
+
+	#emitUnsupported(capability: string, reason: string): void {
+		this.#emit({ kind: "unsupported", capability, reason });
+	}
+
+	async select(
+		title: string,
+		options: string[],
+		dialogOptions?: ExtensionUIDialogOptions,
+	): Promise<string | undefined> {
+		const result = await this.#broker.request(
+			{ kind: "select", title, options, timeout: timeoutFor(dialogOptions) },
+			{ timeoutMs: timeoutFor(dialogOptions), signal: dialogOptions?.signal },
+		);
+		if (isBrokerCancelled(result)) {
+			if (result.reason === "timeout") dialogOptions?.onTimeout?.();
+			return undefined;
+		}
+		if (isUiValue(result) && typeof result.value === "string") return result.value;
+		return undefined;
+	}
+
+	async confirm(title: string, message: string, dialogOptions?: ExtensionUIDialogOptions): Promise<boolean> {
+		const result = await this.#broker.request(
+			{ kind: "confirm", title, message, timeout: timeoutFor(dialogOptions) },
+			{ timeoutMs: timeoutFor(dialogOptions), signal: dialogOptions?.signal },
+		);
+		if (isBrokerCancelled(result)) {
+			if (result.reason === "timeout") dialogOptions?.onTimeout?.();
+			return false;
+		}
+		if (isUiValue(result) && typeof result.value === "boolean") return result.value;
+		return false;
+	}
+
+	async input(
+		title: string,
+		placeholder?: string,
+		dialogOptions?: ExtensionUIDialogOptions,
+	): Promise<string | undefined> {
+		const result = await this.#broker.request(
+			{ kind: "input", title, placeholder, timeout: timeoutFor(dialogOptions) },
+			{ timeoutMs: timeoutFor(dialogOptions), signal: dialogOptions?.signal },
+		);
+		if (isBrokerCancelled(result)) {
+			if (result.reason === "timeout") dialogOptions?.onTimeout?.();
+			return undefined;
+		}
+		if (isUiValue(result) && typeof result.value === "string") return result.value;
+		return undefined;
+	}
+
+	notify(message: string, type?: "info" | "warning" | "error"): void {
+		this.#emit({ kind: "notify", message, type });
+	}
+
+	onTerminalInput(_handler: TerminalInputHandler): () => void {
+		this.#emitUnsupported("ui.terminal_input", "Raw terminal input is not supported by the bridge protocol yet");
+		return () => {};
+	}
+
+	setStatus(key: string, text: string | undefined): void {
+		this.#emit({ kind: "status", key, text });
+	}
+
+	setWorkingMessage(message?: string): void {
+		this.#emit({ kind: "status", key: "working", text: message });
+	}
+
+	setWidget(key: string, content: ExtensionWidgetContent, options?: ExtensionWidgetOptions): void {
+		if (content === undefined || Array.isArray(content)) {
+			this.#emit({ kind: "widget", key, lines: content, placement: options?.placement });
+			return;
+		}
+		this.#emitUnsupported("ui.widget.component", "Component factory widgets are local-only and not serializable");
+	}
+
+	setFooter(_factory?: unknown): void {
+		this.#emitUnsupported("ui.footer.component", "Footer component factories are local-only and not serializable");
+	}
+
+	setHeader(_factory?: unknown): void {
+		this.#emitUnsupported("ui.header.component", "Header component factories are local-only and not serializable");
+	}
+
+	setTitle(title: string): void {
+		this.#emit({ kind: "title", title });
+	}
+
+	async custom<T>(): Promise<T> {
+		this.#emitUnsupported("ui.custom.component", "Custom focused components are local-only and not serializable");
+		throw new Error("Custom focused components are local-only and not serializable through bridge UI context");
+	}
+
+	setEditorText(text: string): void {
+		this.#emit({ kind: "set_editor_text", text });
+	}
+
+	pasteToEditor(text: string): void {
+		this.setEditorText(text);
+	}
+
+	getEditorText(): string {
+		this.#emitUnsupported(
+			"ui.editor.get_text",
+			"Synchronous editor reads are local-only and not supported by bridge UI context",
+		);
+		throw new Error("Synchronous editor reads are local-only and not supported by bridge UI context");
+	}
+
+	async editor(
+		title: string,
+		prefill?: string,
+		dialogOptions?: ExtensionUIDialogOptions,
+		editorOptions?: { promptStyle?: boolean },
+	): Promise<string | undefined> {
+		const result = await this.#broker.request(
+			{ kind: "editor", title, prefill, promptStyle: editorOptions?.promptStyle },
+			{ timeoutMs: timeoutFor(dialogOptions), signal: dialogOptions?.signal },
+		);
+		if (isBrokerCancelled(result)) {
+			if (result.reason === "timeout") dialogOptions?.onTimeout?.();
+			return undefined;
+		}
+		if (isUiUnsupported(result)) return undefined;
+		if (isUiValue(result) && typeof result.value === "string") return result.value;
+		return undefined;
+	}
+
+	setEditorComponent(_factory?: unknown): void {
+		this.#emitUnsupported("ui.editor.component", "Custom editor components are local-only and not serializable");
+	}
+
+	get theme(): Theme {
+		return theme;
+	}
+
+	getAllThemes(): Promise<{ name: string; path: string | undefined }[]> {
+		return Promise.resolve([]);
+	}
+
+	getTheme(_name: string): Promise<Theme | undefined> {
+		return Promise.resolve(undefined);
+	}
+
+	setTheme(_theme: string | Theme): Promise<{ success: boolean; error?: string }> {
+		return Promise.resolve({ success: false, error: "Theme switching is not supported by bridge UI context yet" });
+	}
+
+	getToolsExpanded(): boolean {
+		return false;
+	}
+
+	setToolsExpanded(_expanded: boolean): void {
+		this.#emitUnsupported("ui.tools_expanded", "Tool expansion state is not supported by bridge UI context yet");
+	}
+}

package/src/modes/bridge/event-stream.ts

@@ -0,0 +1,70 @@
+import type { BridgeFrameEnvelope } from "../shared/agent-wire/protocol";
+
+const encoder = new TextEncoder();
+const DEFAULT_REPLAY_LIMIT = 1_000;
+
+function encodeSseFrame(frame: BridgeFrameEnvelope): Uint8Array {
+	return encoder.encode(`data: ${JSON.stringify(frame)}\n\n`);
+}
+
+export class BridgeEventStream {
+	#frames: BridgeFrameEnvelope[] = [];
+	#subscribers = new Set<ReadableStreamDefaultController<Uint8Array>>();
+	#replayLimit: number;
+
+	constructor(replayLimit = DEFAULT_REPLAY_LIMIT) {
+		this.#replayLimit = replayLimit;
+	}
+	get frameCount(): number {
+		return this.#frames.length;
+	}
+
+	publish(frame: BridgeFrameEnvelope): void {
+		this.#frames.push(frame);
+		if (this.#frames.length > this.#replayLimit) this.#frames.splice(0, this.#frames.length - this.#replayLimit);
+		const encoded = encodeSseFrame(frame);
+		for (const controller of this.#subscribers) {
+			try {
+				controller.enqueue(encoded);
+			} catch {
+				this.#subscribers.delete(controller);
+			}
+		}
+	}
+
+	response(lastSeq = 0): Response {
+		let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+		const stream = new ReadableStream<Uint8Array>({
+			start: controller => {
+				streamController = controller;
+				const first = this.#frames[0];
+				if (first && lastSeq > 0 && first.seq > lastSeq + 1) {
+					controller.enqueue(
+						encodeSseFrame({
+							protocol_version: first.protocol_version,
+							session_id: first.session_id,
+							seq: first.seq - 1,
+							frame_id: `reset-${first.seq}`,
+							type: "reset",
+							payload: { reason: "replay_window_exceeded", first_seq: first.seq },
+						}),
+					);
+				}
+				for (const frame of this.#frames) {
+					if (frame.seq > lastSeq) controller.enqueue(encodeSseFrame(frame));
+				}
+				this.#subscribers.add(controller);
+			},
+			cancel: () => {
+				if (streamController) this.#subscribers.delete(streamController);
+			},
+		});
+		return new Response(stream, {
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive",
+			},
+		});
+	}
+}

package/src/modes/components/custom-editor.ts

@@ -1,4 +1,5 @@
 import { Editor, type KeyId, matchesKey, parseKittySequence } from "@gajae-code/tui";
+import { BracketedPasteHandler } from "@gajae-code/tui/bracketed-paste";
 import type { AppKeybinding } from "../../config/keybindings";
 
 type ConfigurableEditorAction = Extract<
@@ -40,6 +41,11 @@ const DEFAULT_ACTION_KEYS: Record<ConfigurableEditorAction, KeyId[]> = {
 	"app.clipboard.copyPrompt": ["alt+shift+c"],
 };
 
+const PASTE_DECISION_TIMEOUT_MS = 5_000;
+const PENDING_PASTE_INPUT_MAX = 64;
+
+type PastePendingClearReason = "timeout" | "queue-limit";
+
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -63,6 +69,10 @@ export class CustomEditor extends Editor {
 	onCopyPrompt?: () => void;
 	/** Called when the configured image-paste shortcut is pressed. */
 	onPasteImage?: () => Promise<boolean>;
+	/** Called before bracketed paste content is inserted. Return true to consume it. */
+	onPasteText?: (text: string) => boolean | Promise<boolean>;
+	/** Called when async paste handling drops queued input instead of replaying it. */
+	onPastePendingInputCleared?: (reason: PastePendingClearReason, droppedInputCount: number) => void;
 	/** Called when the configured dequeue shortcut is pressed. */
 	onDequeue?: () => void;
 	/** Called when Caps Lock is pressed. */
@@ -73,6 +83,11 @@ export class CustomEditor extends Editor {
 	#actionKeys = new Map<ConfigurableEditorAction, KeyId[]>(
 		Object.entries(DEFAULT_ACTION_KEYS).map(([action, keys]) => [action as ConfigurableEditorAction, [...keys]]),
 	);
+	#pasteHandler = new BracketedPasteHandler();
+	#pasteDecisionPending = false;
+	#pasteDecisionToken = 0;
+	#pasteDecisionTimeout: NodeJS.Timeout | undefined;
+	#pendingPasteInput: string[] = [];
 
 	setActionKeys(action: ConfigurableEditorAction, keys: KeyId[]): void {
 		this.#actionKeys.set(action, [...keys]);
@@ -108,7 +123,84 @@ export class CustomEditor extends Editor {
 		this.#customKeyHandlers.clear();
 	}
 
+	#clearPasteDecisionTimeout(): void {
+		if (this.#pasteDecisionTimeout) {
+			clearTimeout(this.#pasteDecisionTimeout);
+			this.#pasteDecisionTimeout = undefined;
+		}
+	}
+
+	#clearPendingPasteState(): number {
+		this.#clearPasteDecisionTimeout();
+		this.#pasteDecisionPending = false;
+		this.#pasteDecisionToken += 1;
+		const droppedInputCount = this.#pendingPasteInput.length;
+		this.#pendingPasteInput = [];
+		return droppedInputCount;
+	}
+
+	#startPasteDecisionTimeout(token: number): void {
+		this.#clearPasteDecisionTimeout();
+		this.#pasteDecisionTimeout = setTimeout(() => {
+			if (token !== this.#pasteDecisionToken) return;
+			const droppedInputCount = this.#clearPendingPasteState();
+			this.onPastePendingInputCleared?.("timeout", droppedInputCount);
+		}, PASTE_DECISION_TIMEOUT_MS);
+		this.#pasteDecisionTimeout.unref?.();
+	}
+
+	dispose(): void {
+		this.#clearPendingPasteState();
+		this.#pasteHandler = new BracketedPasteHandler();
+	}
+
+	#drainPendingPasteInput(initialInput?: string): void {
+		if (initialInput && initialInput.length > 0) {
+			this.handleInput(initialInput);
+		}
+		while (!this.#pasteDecisionPending) {
+			const nextInput = this.#pendingPasteInput.shift();
+			if (nextInput === undefined) break;
+			this.handleInput(nextInput);
+		}
+	}
+
+	#handleBracketedPaste(pasteContent: string, remaining: string): void {
+		const applyPasteResult = (token: number, handled: boolean | undefined) => {
+			if (token !== this.#pasteDecisionToken) return;
+			this.#clearPasteDecisionTimeout();
+			if (!handled) {
+				super.handleInput(`\x1b[200~${pasteContent}\x1b[201~`);
+			}
+			this.#pasteDecisionPending = false;
+			this.#drainPendingPasteInput(remaining);
+		};
+		const pasteResult = this.onPasteText?.(pasteContent);
+
+		if (pasteResult instanceof Promise) {
+			const token = this.#pasteDecisionToken + 1;
+			this.#pasteDecisionToken = token;
+			this.#pasteDecisionPending = true;
+			this.#startPasteDecisionTimeout(token);
+			void pasteResult.then(
+				handled => applyPasteResult(token, handled),
+				() => applyPasteResult(token, false),
+			);
+		} else {
+			applyPasteResult(this.#pasteDecisionToken, pasteResult);
+		}
+	}
+
 	handleInput(data: string): void {
+		if (this.#pasteDecisionPending) {
+			this.#pendingPasteInput.push(data);
+			if (this.#pendingPasteInput.length > PENDING_PASTE_INPUT_MAX) {
+				const droppedInputCount = this.#clearPendingPasteState();
+				this.onPastePendingInputCleared?.("queue-limit", droppedInputCount);
+			}
+			return;
+		}
+
 		const parsed = parseKittySequence(data);
 		if (parsed && (parsed.modifier & 64) !== 0 && this.onCapsLock) {
 			// Caps Lock is modifier bit 64
@@ -116,6 +208,15 @@ export class CustomEditor extends Editor {
 			return;
 		}
 
+		if (this.onPasteText) {
+			const paste = this.#pasteHandler.process(data);
+			if (paste.handled) {
+				if (paste.pasteContent !== undefined) {
+					this.#handleBracketedPaste(paste.pasteContent, paste.remaining);
+				}
+				return;
+			}
+		}
 		// Intercept configured image paste (async - fires and handles result)
 		if (this.#matchesAction(data, "app.clipboard.pasteImage") && this.onPasteImage) {
 			void this.onPasteImage();

package/src/modes/components/hook-selector.ts

@@ -21,6 +21,22 @@ import { matchesAppExternalEditor, matchesSelectCancel } from "../../modes/utils
 import { CountdownTimer } from "./countdown-timer";
 import { DynamicBorder } from "./dynamic-border";
 
+const SGR_MOUSE_PRESS_PATTERN = /^\x1b\[<(\d+);\d+;\d+M$/;
+const MOUSE_WHEEL_TITLE_SCROLL_ROWS = 3;
+
+function getMouseWheelTitleScrollRows(keyData: string): number {
+	const match = SGR_MOUSE_PRESS_PATTERN.exec(keyData);
+	if (!match) return 0;
+
+	const button = Number.parseInt(match[1] ?? "", 10);
+	if (!Number.isFinite(button) || (button & 64) === 0) return 0;
+
+	const wheelDirection = button & 3;
+	if (wheelDirection === 0) return -MOUSE_WHEEL_TITLE_SCROLL_ROWS;
+	if (wheelDirection === 1) return MOUSE_WHEEL_TITLE_SCROLL_ROWS;
+	return 0;
+}
+
 export interface HookSelectorOptions {
 	tui?: TUI;
 	timeout?: number;
@@ -125,11 +141,10 @@ class ScrollableTitle extends Container {
  * `maxVisibleRows`; everything that depends on terminal width is recomputed
  * on each render so resize Just Works.
  *
- * `maxVisibleRows` is a sibling budget before it is a hard cap: surrounding
- * options shrink first so the focused option is never clipped. The single
- * allowed overflow exception is when the focused option's wrapped block
- * alone exceeds the budget — in that case the focused option is rendered
- * fully with zero siblings.
+ * `maxVisibleRows` is a hard viewport budget for every rendered option-list
+ * row. Surrounding options shrink first; if the focused option alone would
+ * exceed the remaining budget, it is compacted to contextual rows plus an
+ * omitted-rows marker so controls stay reachable for untrusted long labels.
  */
 class FocusAwareList extends Container {
 	#options: string[] = [];
@@ -168,19 +183,20 @@ class FocusAwareList extends Container {
 			theme.fg("accent", t),
 		);
 		const focusedWrappedSegments = wrapTextWithAnsi(focusedLabel, availableLabelWidth);
-		const focusedRows = Math.max(1, focusedWrappedSegments.length);
 
-		// Decide whether the position marker is going to be shown. We make a
-		// pessimistic first pass assuming the marker is needed; if the window
-		// ends up covering every option we drop it.
+		// Reserve one row for the option position marker only when the focused
+		// block itself must be compacted. Moderate focused labels keep the legacy
+		// wrap-focused behavior and spend the full viewport on label context.
 		const totalOptions = this.#options.length;
-		const willHaveSiblings = totalOptions > 1;
-		const wouldNeedMarker = willHaveSiblings; // tentative; refined below
-		const markerSlot = wouldNeedMarker ? 1 : 0;
+		const mustCompactFocused = focusedWrappedSegments.length > this.#maxVisibleRows;
+		const positionMarkerSlot = mustCompactFocused && totalOptions > 1 ? 1 : 0;
+		const focusedBudget = Math.max(1, this.#maxVisibleRows - positionMarkerSlot);
+		const focusedSegments = this.#capFocusedSegments(focusedWrappedSegments, focusedBudget, availableLabelWidth);
+		const focusedRows = Math.max(1, focusedSegments.length);
 
-		// Sibling budget. If the focused block alone is over budget, render it
-		// fully with zero siblings (only allowed overflow exception).
-		const siblingBudget = Math.max(0, this.#maxVisibleRows - focusedRows - markerSlot);
+		// Sibling budget. If the focused block consumes the available viewport,
+		// render it with zero siblings and the reserved position marker.
+		const siblingBudget = Math.max(0, this.#maxVisibleRows - focusedRows - positionMarkerSlot);
 
 		// Distribute sibling slots around focus, preferring closest options.
 		const availableAbove = this.#selectedIndex;
@@ -203,8 +219,8 @@ class FocusAwareList extends Container {
 			if (i === this.#selectedIndex) {
 				// Emit focused wrapped rows. Cursor only on row 0; continuation
 				// rows are whitespace-aligned under the label start.
-				for (let r = 0; r < focusedWrappedSegments.length; r++) {
-					const segment = focusedWrappedSegments[r] ?? "";
+				for (let r = 0; r < focusedSegments.length; r++) {
+					const segment = focusedSegments[r] ?? "";
 					rows.push(r === 0 ? styledSelectedPrefix + segment : continuationPrefix + segment);
 				}
 			} else {
@@ -217,13 +233,33 @@ class FocusAwareList extends Container {
 			}
 		}
 
-		if (showMarker) {
+		if (showMarker && rows.length < this.#maxVisibleRows) {
 			rows.push(theme.fg("dim", `  (${this.#selectedIndex + 1}/${totalOptions})`));
 		}
 
 		return this.#outline ? this.#wrapOutline(rows, width) : rows;
 	}
 
+	#capFocusedSegments(segments: string[], maxRows: number, availableLabelWidth: number): string[] {
+		const rows = segments.length > 0 ? segments : [""];
+		const budget = Math.max(1, Math.floor(maxRows));
+		if (rows.length <= budget) return rows;
+
+		if (budget === 1) {
+			return [truncateToWidth(`… ${rows.length - 1} wrapped rows omitted …`, availableLabelWidth)];
+		}
+
+		if (budget === 2) {
+			return [rows[0] ?? "", truncateToWidth(`… ${rows.length - 1} wrapped rows omitted …`, availableLabelWidth)];
+		}
+
+		const tailRows = Math.max(1, Math.floor((budget - 2) / 2));
+		const headRows = Math.max(1, budget - 1 - tailRows);
+		const omittedRows = Math.max(1, rows.length - headRows - tailRows);
+		const marker = truncateToWidth(`… ${omittedRows} wrapped rows omitted …`, availableLabelWidth);
+		return [...rows.slice(0, headRows), marker, ...rows.slice(rows.length - tailRows)];
+	}
+
 	#wrapOutline(rows: string[], width: number): string[] {
 		// Mirror the outline border drawn by `OutlinedList.render(width)`. The
 		// rows passed in are already constrained to `innerWidth` by
@@ -381,6 +417,13 @@ export class HookSelectorComponent extends Container {
 		// Reset countdown on any interaction
 		this.#countdown?.reset();
 
+		if (this.#scrollTitleRows !== undefined) {
+			const wheelRows = getMouseWheelTitleScrollRows(keyData);
+			if (wheelRows !== 0) {
+				this.#scrollableTitle?.scrollBy(wheelRows);
+				return;
+			}
+		}
 		if (this.#scrollTitleRows !== undefined && matchesKey(keyData, "pageUp")) {
 			this.#scrollableTitle?.scrollBy(-this.#scrollTitleRows);
 			return;

package/src/modes/components/jobs-overlay-model.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure model helpers for the jobs overlay.
+ *
+ * Kept free of UI/Component dependencies so the grouping/ordering and
+ * detail-formatting logic is unit-testable. The selector controller wires these
+ * SelectItem lists into nested SelectLists (list -> detail -> confirm).
+ */
+import type { SelectItem } from "@gajae-code/tui";
+import type { JobsSnapshot } from "../jobs-observer";
+
+export type JobRefKind = "monitor" | "cron";
+
+export interface JobRef {
+	kind: JobRefKind;
+	id: string;
+}
+
+const PROMPT_PREVIEW_MAX = 60;
+
+function preview(text: string, max = PROMPT_PREVIEW_MAX): string {
+	const oneLine = text.replace(/\s+/g, " ").trim();
+	return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+
+/** Compact relative time, e.g. "in 5m", "2m ago", "now". */
+export function formatRelative(targetMs: number | undefined, nowMs = Date.now()): string {
+	if (targetMs === undefined) return "—";
+	const deltaMs = targetMs - nowMs;
+	const abs = Math.abs(deltaMs);
+	const mins = Math.round(abs / 60_000);
+	if (mins < 1) return "now";
+	const unit = mins >= 60 ? `${Math.round(mins / 60)}h` : `${mins}m`;
+	return deltaMs >= 0 ? `in ${unit}` : `${unit} ago`;
+}
+
+/** Parse a list item value back into a job reference. */
+export function parseJobRef(value: string): JobRef | null {
+	const sep = value.indexOf(":");
+	if (sep === -1) return null;
+	const kind = value.slice(0, sep);
+	const id = value.slice(sep + 1);
+	if ((kind === "monitor" || kind === "cron") && id.length > 0) {
+		return { kind, id };
+	}
+	return null;
+}
+
+/**
+ * Build the grouped jobs list: monitors first (newest-first), then crons
+ * (newest-first). The snapshot arrays are already sorted newest-first.
+ */
+export function buildJobsListItems(snapshot: JobsSnapshot): SelectItem[] {
+	const items: SelectItem[] = [];
+	for (const monitor of snapshot.monitors) {
+		items.push({
+			value: `monitor:${monitor.id}`,
+			label: `monitor · ${preview(monitor.label, 40)}`,
+			description: monitor.status,
+			hint: monitor.status === "failed" ? "failed" : undefined,
+		});
+	}
+	for (const cron of snapshot.crons) {
+		items.push({
+			value: `cron:${cron.id}`,
+			label: `cron · ${cron.humanSchedule}`,
+			description: preview(cron.prompt),
+		});
+	}
+	return items;
+}
+
+/**
+ * Build the detail-level items for a job: read-only info rows (value "noop"),
+ * then the destructive action, then a back row. `output` is the bounded monitor
+ * output tail (ignored for cron jobs).
+ */
+export function buildJobDetailItems(snapshot: JobsSnapshot, ref: JobRef, output = ""): SelectItem[] {
+	if (ref.kind === "monitor") {
+		const monitor = snapshot.monitors.find(m => m.id === ref.id);
+		if (!monitor) return [{ value: "back", label: "Back (job no longer present)" }];
+		const lastOutput = output.trim().split("\n").filter(Boolean).slice(-1)[0] ?? "(no output captured)";
+		return [
+			{ value: "noop", label: "Status", description: monitor.status },
+			{ value: "noop", label: "Label", description: preview(monitor.label) },
+			{ value: "noop", label: "Started", description: formatRelative(monitor.startTime) },
+			{ value: "noop", label: "Output", description: preview(lastOutput, 80) },
+			{ value: "action:cancel", label: "Cancel this monitor", hint: "stops the running job" },
+			{ value: "back", label: "Back" },
+		];
+	}
+	const cron = snapshot.crons.find(c => c.id === ref.id);
+	if (!cron) return [{ value: "back", label: "Back (job no longer present)" }];
+	return [
+		{ value: "noop", label: "Schedule", description: `${cron.humanSchedule} (${cron.cronExpression})` },
+		{ value: "noop", label: "Recurring", description: cron.recurring ? "yes" : "no" },
+		{ value: "noop", label: "Next fire", description: formatRelative(cron.nextFireAt) },
+		{ value: "noop", label: "Prompt", description: preview(cron.prompt, 80) },
+		{ value: "action:delete", label: "Delete this cron", hint: "removes the schedule" },
+		{ value: "back", label: "Back" },
+	];
+}
+
+/** Yes/No confirm items for a destructive action. */
+export function buildConfirmItems(actionLabel: string): SelectItem[] {
+	return [
+		{ value: "no", label: `No, keep it` },
+		{ value: "yes", label: `Yes, ${actionLabel}` },
+	];
+}