@haywoodmarx/agent-pager 0.1.3 → 0.2.1

package/dist/src/shared/versions.js

@@ -0,0 +1,26 @@
+/**
+ * Read the `major.minor.patch` numbers of a version string.
+ * @param version - Version text, such as a runtime's reported version or a package release.
+ * @param extent - `prefix` accepts trailing text such as a prerelease or build suffix and ignores it;
+ * `exact` rejects any version carrying one.
+ * @returns - The three numbers, or undefined when the text does not start with, or is not exactly, a
+ * numeric version.
+ */
+export function parseNumericVersion(version, extent) {
+    const match = (extent === "exact" ? /^(\d+)\.(\d+)\.(\d+)$/u : /^(\d+)\.(\d+)\.(\d+)/u).exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+/**
+ * Order two numeric versions.
+ * @param left - First version.
+ * @param right - Second version.
+ * @returns - Negative when `left` is lower, positive when it is higher, zero when they are equal.
+ */
+export function compareNumericVersions(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}

package/dist/src/tui/agent-tree.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId } from "../broker/protocol.js";
-import type { OperatorAgent, OperatorCommand, OperatorRepository } from "../operator/protocol.js";
-import type { TuiOperatorModel, TuiOperatorModelState, TuiOperatorViewState } from "./model.js";
+import { type OperatorAgent, type OperatorCommand, type OperatorRepository } from "../operator/protocol.js";
+import { type TuiOperatorModel, type TuiOperatorModelState, type TuiOperatorViewState } from "./model.js";
 import type { TuiTheme } from "./theme.js";
 /** Agent rows grouped by their projected repository without creating broker scope. */
 export type TuiRepositoryAgentGroup = {
@@ -12,7 +12,7 @@ export type TuiRepositoryAgentGroup = {
     readonly archived: readonly OperatorAgent[];
 };
 /** One focusable action offered for a selected agent row. */
-export type TuiAgentContextAction = "ping" | "details" | "archive" | "collapse";
+export type TuiAgentContextAction = "ping" | "details" | "archive" | "purge" | "collapse";
 /** One focusable action offered for a selected workspace row. */
 export type TuiWorkspaceContextAction = "hide" | "unhide";
 /** A keyboard-reachable projected tree row. */
@@ -34,7 +34,7 @@ export type AgentTreeProps = {
     readonly model: TuiOperatorModel;
     /** Semantic terminal palette. */
     readonly theme: Readonly<TuiTheme>;
-    /** Submits the broker command a tree action raised, a ping or an archive. */
+    /** Submits the broker command a tree action raised. */
     readonly onCommand: (command: OperatorCommand) => void;
     /** Enables terminal colours without changing textual distinctions. */
     readonly colorEnabled?: boolean;
@@ -43,6 +43,9 @@ export type AgentTreeProps = {
 };
 /**
  * Group projected agents under their projected repositories in stable registration order.
+ *
+ * A repository with no projected agent has no group. It stays in the projection, so the view state
+ * kept for it outlives the time it spends empty.
  * @param snapshot - Authoritative projection currently installed by the client model.
  * @returns Repository groups suitable for the tree presentation.
  */
@@ -100,7 +103,7 @@ export declare function reduceAgentTreeContextAction(state: TuiOperatorModelStat
  * Reduce one keyboard command without depending on an OpenTUI input source.
  * @param state - Current authoritative projection and local presentation state.
  * @param key - Normalized OpenTUI key name.
- * @returns The next model-owned view and an optional broker command, a ping or an archive.
+ * @returns The next model-owned view and an optional broker command.
  */
 export declare function reduceAgentTreeKey(state: TuiOperatorModelState, key: string): TuiAgentTreeKeyResult;
 /**

package/dist/src/tui/agent-tree.js

@@ -1,10 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "@opentui/react/jsx-runtime";
 import { useKeyboard, useTerminalDimensions } from "@opentui/react";
 import { archivedOperatorRepositoryIds, isOperatorAgentArchived, operatorArchiveReason, } from "../operator/agent-projection.js";
+import { OPERATOR_PURGE_TARGET_LIMIT, } from "../operator/protocol.js";
+import { selectTuiPurgeableAgents, } from "./model.js";
 import { Line, Overlay, fitOverlayColumns, PaneBar, Rule, SCROLLBAR_RESERVED_COLUMNS, VERTICAL_SCROLL_STYLE, useTuiModel, } from "./chrome.js";
 import { AGENT_TREE_COLUMNS, IDENTITY_LABEL_GUTTER, agentColor, agentDetail, agentHandleText, formatClock, padCells, SELECTION_GUTTER_GLYPH, stepWrappingIndex, truncateCells, } from "./presentation.js";
 /**
  * Group projected agents under their projected repositories in stable registration order.
+ *
+ * A repository with no projected agent has no group. It stays in the projection, so the view state
+ * kept for it outlives the time it spends empty.
  * @param snapshot - Authoritative projection currently installed by the client model.
  * @returns Repository groups suitable for the tree presentation.
  */
@@ -17,13 +22,17 @@ export function selectTuiRepositoryAgentGroups(snapshot) {
         agents.push(agent);
         agentsByRepository.set(agent.repository.repositoryId, agents);
     }
-    const groups = snapshot.repositories.map((repository) => {
+    const groups = snapshot.repositories.flatMap((repository) => {
         const agents = agentsByRepository.get(repository.id) ?? [];
-        return {
-            repository,
-            active: agents.filter((agent) => !isOperatorAgentArchived(agent)),
-            archived: agents.filter((agent) => isOperatorAgentArchived(agent)),
-        };
+        if (agents.length === 0)
+            return [];
+        return [
+            {
+                repository,
+                active: agents.filter((agent) => !isOperatorAgentArchived(agent)),
+                archived: agents.filter((agent) => isOperatorAgentArchived(agent)),
+            },
+        ];
     });
     // Archived workspaces sink below the ones still working, the same way an archived agent sits below
     // its peers. Neither ordering is stable-sorted by anything else, so the projection's order holds
@@ -158,7 +167,7 @@ export function executeAgentTreeResult(model, onCommand, result) {
  */
 function reduceAgentTreeArchivedToggle(state, repositoryId) {
     const view = state.view;
-    const group = selectTuiRepositoryAgentGroups(state.snapshot).find((candidate) => candidate.repository.id === repositoryId);
+    const group = repositoryGroup(state, repositoryId);
     if (!group)
         return { view };
     const sections = new Map(view.archivedSections);
@@ -192,6 +201,8 @@ export function reduceAgentTreeContextAction(state, action) {
     // selected it.
     if (action === "archive")
         return { view: { ...view, overlay: { kind: "archive_confirm", agentId: agent.id } } };
+    if (action === "purge")
+        return { view: { ...view, overlay: { kind: "purge_confirm", target: { kind: "agent", agentId: agent.id } } } };
     const archived = isOperatorAgentArchived(agent);
     const collapsedRepositories = new Set(view.collapsedRepositories);
     if (!archived)
@@ -207,11 +218,39 @@ export function reduceAgentTreeContextAction(state, action) {
         },
     };
 }
+/**
+ * Open the purge confirmation for the archive section the menu was opened on.
+ * @param state - Current authoritative facts and local view state.
+ * @returns - The confirmation, naming the section's agents up to the purge limit, or the menu closed
+ * when the section has emptied.
+ */
+function reduceArchivedContextAction(state) {
+    const view = state.view;
+    const overlay = view.overlay;
+    if (overlay.kind !== "context_menu" || overlay.target !== "archived")
+        return { view };
+    const archived = archivedSection(state, overlay.repositoryId);
+    if (archived.length === 0)
+        return { view: { ...view, focus: view.overlayReturnFocus, overlay: { kind: "none" }, contextActionIndex: 0 } };
+    const agentIds = archived.slice(0, OPERATOR_PURGE_TARGET_LIMIT).map((agent) => agent.id);
+    return {
+        view: {
+            ...view,
+            overlay: { kind: "purge_confirm", target: { kind: "archived", repositoryId: overlay.repositoryId, agentIds } },
+        },
+    };
+}
+function repositoryGroup(state, repositoryId) {
+    return selectTuiRepositoryAgentGroups(state.snapshot).find((group) => group.repository.id === repositoryId);
+}
+function archivedSection(state, repositoryId) {
+    return repositoryGroup(state, repositoryId)?.archived ?? [];
+}
 /**
  * Reduce one keyboard command without depending on an OpenTUI input source.
  * @param state - Current authoritative projection and local presentation state.
  * @param key - Normalized OpenTUI key name.
- * @returns The next model-owned view and an optional broker command, a ping or an archive.
+ * @returns The next model-owned view and an optional broker command.
  */
 export function reduceAgentTreeKey(state, key) {
     const view = state.view;
@@ -237,6 +276,23 @@ export function reduceAgentTreeKey(state, key) {
             command: { type: "archive_agent", targetAgentId: target },
         };
     }
+    if (view.overlay.kind === "purge_confirm") {
+        if (key === "escape")
+            return close();
+        if (!activates(key))
+            return { view };
+        const targetAgentIds = selectTuiPurgeableAgents(view.overlay.target, state.snapshot?.agents ?? []).map((entry) => entry.id);
+        if (targetAgentIds.length === 0)
+            return close();
+        return {
+            view: {
+                ...close().view,
+                ...rescopedAgentLog,
+                selection: selectionAfterPurge(state, view.overlay.target, targetAgentIds),
+            },
+            command: { type: "purge_agents", targetAgentIds },
+        };
+    }
     if (view.overlay.kind === "context_menu" && view.overlay.target === "workspace") {
         if (key === "escape")
             return close();
@@ -244,6 +300,13 @@ export function reduceAgentTreeKey(state, key) {
             return { view };
         return reduceWorkspaceContextAction(state, workspaceContextActions(state)[0] ?? "hide");
     }
+    if (view.overlay.kind === "context_menu" && view.overlay.target === "archived") {
+        if (key === "escape")
+            return close();
+        if (!activates(key))
+            return { view };
+        return reduceArchivedContextAction(state);
+    }
     // The message menu shares this overlay kind, and its own component answers its keys.
     if (view.overlay.kind === "context_menu" && view.overlay.target === "agent") {
         if (key === "escape")
@@ -275,7 +338,7 @@ export function reduceAgentTreeKey(state, key) {
         },
     });
     if (key === "up" || key === "down") {
-        const current = rows.findIndex((row) => JSON.stringify(rowSelection(row)) === JSON.stringify(view.selection));
+        const current = selectedRowIndex(rows, view.selection);
         const step = current < 0 ? 0 : current + (key === "up" ? -1 : 1);
         const next = rows[Math.min(Math.max(step, 0), rows.length - 1)];
         return next ? select(next) : { view };
@@ -293,11 +356,11 @@ export function reduceAgentTreeKey(state, key) {
                 contextActionIndex: 0,
             },
         };
-    if (key === "a" && view.selection?.kind === "workspace")
+    if (key === "a" && (view.selection?.kind === "workspace" || view.selection?.kind === "archived"))
         return {
             view: {
                 ...view,
-                overlay: { kind: "context_menu", target: "workspace", repositoryId: view.selection.repositoryId },
+                overlay: { kind: "context_menu", target: view.selection.kind, repositoryId: view.selection.repositoryId },
                 overlayReturnFocus: view.focus,
                 contextActionIndex: 0,
             },
@@ -359,13 +422,26 @@ export function AgentTree({ model, theme, onCommand, colorEnabled = true, width
             return;
         // Every pane's handler receives this same key, and a reduction carries a whole view, so one
         // taken from the rendered snapshot overwrites whatever another handler decided.
+        const overlayOpen = model.state.view.overlay.kind !== "none";
         const result = reduceAgentTreeKey(model.state, key.name);
+        // A key that closes the tree's overlay is spent on it; the shell's handler, when it runs after this
+        // one, would otherwise read it again against the closed view.
+        if (overlayOpen && result.view.overlay.kind === "none")
+            key.preventDefault();
         executeAgentTreeResult(model, onCommand, result);
     });
     // A tree whose every workspace is hidden still draws the hidden section, the only way to bring one back.
     if (all.length === 0)
         return (_jsx("box", { flexGrow: 1, justifyContent: "center", alignItems: "center", children: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "no agents connected" }) }));
-    return (_jsxs("box", { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx("box", { paddingLeft: 1, paddingRight: 1, flexShrink: 0, children: _jsx(Line, { children: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "AGENTS" }) }) }), _jsx(Line, {}), _jsxs("scrollbox", { flexGrow: 1, focused: focus, paddingLeft: 1, paddingRight: 1, style: VERTICAL_SCROLL_STYLE, children: [groups.map((group) => (_jsx(RepositoryRows, { group: group, state: state, theme: theme, colorEnabled: colorEnabled, width: width, onToggleArchived: toggleArchivedSection, onSelectRepository: (repository) => update((view) => ({
+    return (_jsxs("box", { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx("box", { paddingLeft: 1, paddingRight: 1, flexShrink: 0, children: _jsx(Line, { children: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "AGENTS" }) }) }), _jsx(Line, {}), _jsxs("scrollbox", { flexGrow: 1, focused: focus, paddingLeft: 1, paddingRight: 1, style: VERTICAL_SCROLL_STYLE, children: [groups.map((group) => (_jsx(RepositoryRows, { group: group, state: state, theme: theme, colorEnabled: colorEnabled, width: width, onToggleArchived: toggleArchivedSection, onArchivedContext: (repository) => update((view) => ({
+                            ...view,
+                            focus: "tree",
+                            ...rescopedAgentLog,
+                            selection: { kind: "archived", repositoryId: repository.id },
+                            overlay: { kind: "context_menu", target: "archived", repositoryId: repository.id },
+                            overlayReturnFocus: view.focus,
+                            contextActionIndex: 0,
+                        })), onSelectRepository: (repository) => update((view) => ({
                             ...view,
                             focus: "tree",
                             ...rescopedAgentLog,
@@ -420,11 +496,21 @@ export function AgentTreeOverlay({ model, theme, onCommand, colorEnabled = true
                 state.snapshot?.agents.find((agent) => agent.id === overlay.agentId)?.repository.repositoryId), theme: theme, colorEnabled: colorEnabled }));
     if (overlay.kind === "archive_confirm")
         return (_jsx(ArchiveConfirmOverlay, { agent: state.snapshot?.agents.find((agent) => agent.id === overlay.agentId), theme: theme }));
-    if (overlay.kind === "context_menu" && overlay.target === "workspace")
-        return (_jsx(WorkspaceContextOverlay, { actions: workspaceContextActions(state), theme: theme, onAction: (action) => executeAgentTreeResult(model, onCommand, reduceWorkspaceContextAction(model.state, action)) }));
+    if (overlay.kind === "purge_confirm")
+        return (_jsx(PurgeConfirmOverlay, { target: overlay.target, agents: selectTuiPurgeableAgents(overlay.target, state.snapshot?.agents ?? []), sectionSize: overlay.target.kind === "archived" ? archivedSection(state, overlay.target.repositoryId).length : 1, theme: theme }));
+    if (overlay.kind === "context_menu" && overlay.target === "archived")
+        return (_jsx(SingleActionOverlay, { label: "purge archived", theme: theme, onAction: () => executeAgentTreeResult(model, onCommand, reduceArchivedContextAction(model.state)) }));
+    if (overlay.kind === "context_menu" && overlay.target === "workspace") {
+        const [action] = workspaceContextActions(state);
+        return action === undefined ? null : (_jsx(SingleActionOverlay, { label: workspaceContextActionLabels[action], theme: theme, onAction: () => {
+                const [current] = workspaceContextActions(model.state);
+                if (current !== undefined)
+                    executeAgentTreeResult(model, onCommand, reduceWorkspaceContextAction(model.state, current));
+            } }));
+    }
     return overlay.kind === "context_menu" && overlay.target === "agent" ? (_jsx(AgentContextOverlay, { actionIndex: state.view.contextActionIndex, theme: theme, onAction: (action) => executeAgentTreeResult(model, onCommand, reduceAgentTreeContextAction(model.state, action)) })) : null;
 }
-function RepositoryRows({ group, state, theme, colorEnabled, width, onToggleArchived, onSelectRepository, onSelectAgent, onContext, }) {
+function RepositoryRows({ group, state, theme, colorEnabled, width, onToggleArchived, onArchivedContext, onSelectRepository, onSelectAgent, onContext, }) {
     const expanded = !state.view.collapsedRepositories.has(group.repository.id);
     const archivedExpanded = isTuiArchivedSectionOpen(state.view, group);
     const focused = state.view.focus === "tree";
@@ -438,7 +524,12 @@ function RepositoryRows({ group, state, theme, colorEnabled, width, onToggleArch
     const archivedColor = archivedSelected && focused ? theme.structure.selection.text : theme.structure.rulesAndLabels;
     return (_jsxs("box", { flexDirection: "column", children: [_jsxs("box", { height: 1, flexDirection: "row", onMouseDown: () => onSelectRepository(group.repository), children: [_jsx(SelectionGutter, { marked: selectedRepository, theme: theme }), _jsx("box", { flexGrow: 1, flexDirection: "row", ...(selectedRepository && focused ? { backgroundColor: theme.structure.selection.background } : {}), children: _jsx("text", { fg: repositoryColor, children: `${expanded ? "▾" : "▸"} ${truncateCells(group.repository.name, width - 6 - SCROLLBAR_RESERVED_COLUMNS)}` }) })] }), expanded
                 ? group.active.map((agent, index) => (_jsx(AgentRow, { agent: agent, state: state, theme: theme, colorEnabled: colorEnabled, width: width, last: group.archived.length === 0 && index === group.active.length - 1, onSelect: onSelectAgent, onContext: onContext }, agent.id)))
-                : null, expanded && group.archived.length > 0 ? (_jsxs(_Fragment, { children: [_jsxs("box", { height: 1, flexDirection: "row", onMouseDown: () => onToggleArchived(group.repository), children: [_jsx(SelectionGutter, { marked: archivedSelected, theme: theme }), _jsx("box", { flexGrow: 1, flexDirection: "row", ...(archivedSelected && focused ? { backgroundColor: theme.structure.selection.background } : {}), children: _jsx("text", { fg: archivedColor, children: `└ ${archivedExpanded ? "▾" : "▸"} archived · ${String(group.archived.length)}` }) })] }), archivedExpanded
+                : null, expanded && group.archived.length > 0 ? (_jsxs(_Fragment, { children: [_jsxs("box", { height: 1, flexDirection: "row", onMouseDown: (event) => {
+                            if (event.button === 2)
+                                onArchivedContext(group.repository);
+                            else
+                                onToggleArchived(group.repository);
+                        }, children: [_jsx(SelectionGutter, { marked: archivedSelected, theme: theme }), _jsx("box", { flexGrow: 1, flexDirection: "row", ...(archivedSelected && focused ? { backgroundColor: theme.structure.selection.background } : {}), children: _jsx("text", { fg: archivedColor, children: `└ ${archivedExpanded ? "▾" : "▸"} archived · ${String(group.archived.length)}` }) })] }), archivedExpanded
                         ? group.archived.map((agent, index) => (_jsx(ArchivedAgentRow, { agent: agent, last: index === group.archived.length - 1, state: state, theme: theme, width: width, onSelect: onSelectAgent, onContext: onContext }, agent.id)))
                         : null] })) : null, _jsx("box", { height: 1 })] }));
 }
@@ -525,7 +616,32 @@ function ArchiveConfirmOverlay({ agent, theme, }) {
         return null;
     return (_jsxs(Overlay, { theme: theme, width: ARCHIVE_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.states.failed, children: `archive ${agentHandleText(agent.alias)}?` }), right: null }), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: ARCHIVE_CONFIRM_FOOTER_KEYS }), right: null })] }));
 }
-const contextActions = ["ping", "details", "archive", "collapse"];
+/** Keys the purge confirmation advertises in its footer. */
+const PURGE_CONFIRM_FOOTER_KEYS = "⏎ purge  esc cancel";
+const PURGE_OVERLAY_COLUMNS = 44;
+/**
+ * Confirm a purge, naming the agent it deletes or how many archived agents it deletes.
+ * @param properties - What the confirmation names, the agents it would delete now, how many agents
+ * the archive section holds now, and the palette.
+ * @returns - Confirmation overlay, or nothing once there is nothing left to purge.
+ */
+function PurgeConfirmOverlay({ target, agents, sectionSize, theme, }) {
+    const [only] = agents;
+    if (only === undefined)
+        return null;
+    const plural = agents.length !== 1;
+    const partial = sectionSize > agents.length;
+    const count = partial ? `${String(agents.length)} of ${String(sectionSize)}` : String(agents.length);
+    const subject = target.kind === "agent" ? agentHandleText(only.alias) : `${count} archived agent${plural || partial ? "s" : ""}`;
+    const running = agents.filter((agent) => agent.adapter.state === "connected").length;
+    return (_jsxs(Overlay, { theme: theme, width: PURGE_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.states.failed, children: `purge ${subject}?` }), right: null }), _jsx(Rule, { theme: theme }), _jsxs("box", { flexDirection: "column", paddingLeft: 1, paddingRight: 1, children: [_jsx(Line, { children: _jsx("text", { fg: theme.structure.bodyText, children: plural ? "deletes the agents and their history," : "deletes the agent and its history," }) }), _jsx(Line, { children: _jsx("text", { fg: theme.structure.bodyText, children: "except messages with remaining agents;" }) }), running > 0 ? (_jsx(Line, { children: _jsx("text", { fg: theme.structure.bodyText, children: !plural
+                                ? "ends its running session;"
+                                : `ends ${String(running)} running session${running === 1 ? "" : "s"};` }) })) : null, _jsx(Line, { children: _jsx("text", { fg: theme.structure.bodyText, children: "this cannot be undone" }) })] }), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: PURGE_CONFIRM_FOOTER_KEYS }), right: null })] }));
+}
+function SingleActionOverlay({ label, theme, onAction, }) {
+    return (_jsxs(Overlay, { theme: theme, width: CONTEXT_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "Actions" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), _jsx("box", { height: 1, backgroundColor: theme.structure.selection.background, onMouseDown: onAction, children: _jsx("text", { fg: theme.structure.selection.text, children: ` ${label}` }) }), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: CONTEXT_FOOTER_KEYS }), right: null })] }));
+}
+const contextActions = ["ping", "details", "archive", "purge", "collapse"];
 /**
  * List the actions offered for the workspace the menu was opened on.
  * @param state - Current model state, holding what is hidden.
@@ -545,11 +661,9 @@ const contextActionLabels = {
     ping: "ping inbox",
     details: "details",
     archive: "archive agent",
+    purge: "purge agent",
     collapse: "collapse workspace",
 };
-function WorkspaceContextOverlay({ actions, theme, onAction, }) {
-    return (_jsxs(Overlay, { theme: theme, width: CONTEXT_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "Actions" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), actions.map((action) => (_jsx("box", { height: 1, backgroundColor: theme.structure.selection.background, onMouseDown: () => onAction(action), children: _jsx("text", { fg: theme.structure.selection.text, children: ` ${workspaceContextActionLabels[action]}` }) }, action))), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: CONTEXT_FOOTER_KEYS }), right: null })] }));
-}
 function AgentContextOverlay({ actionIndex, theme, onAction, }) {
     return (_jsxs(Overlay, { theme: theme, width: CONTEXT_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "Actions" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), contextActions.map((action, index) => (_jsxs("box", { flexDirection: "column", children: [action === "collapse" ? _jsx(Rule, { theme: theme }) : null, _jsx("box", { height: 1, ...(index === actionIndex ? { backgroundColor: theme.structure.selection.background } : {}), onMouseDown: () => onAction(action), children: _jsx("text", { fg: index === actionIndex ? theme.structure.selection.text : theme.structure.emphasis, children: ` ${contextActionLabels[action]}` }) })] }, action))), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: CONTEXT_FOOTER_KEYS }), right: null })] }));
 }
@@ -586,6 +700,65 @@ function selectionAfterArchive(state, agentId) {
     const next = index < 0 ? undefined : rows[index + 1];
     return next ? rowSelection(next) : { kind: "workspace", repositoryId };
 }
+/**
+ * Choose what the tree selects once a purge lands.
+ *
+ * A section purge selects the section while it keeps an agent, or else its workspace. An agent purge
+ * selects the workspace when it takes the workspace's last working agent, since the workspace then
+ * collapses. Neither selects a workspace the purge leaves with no agent, since the tree has no row
+ * for it; the selection then moves to the nearest row below that outlives the purge, or else the
+ * nearest above.
+ * @param state - Current authoritative facts and local view state.
+ * @param target - What the confirmed purge named.
+ * @param agentIds - Agents about to be purged.
+ * @returns - Selection to hold after the purge lands.
+ */
+function selectionAfterPurge(state, target, agentIds) {
+    const purged = new Set(agentIds);
+    const agents = state.snapshot?.agents ?? [];
+    const kept = (group) => group.some((agent) => !purged.has(agent.id));
+    const groups = new Map(selectTuiRepositoryAgentGroups(state.snapshot).map((group) => [group.repository.id, group]));
+    const keepsArchived = (repositoryId) => kept(groups.get(repositoryId)?.archived ?? []);
+    const keepsAgents = (repositoryId) => keepsArchived(repositoryId) || kept(groups.get(repositoryId)?.active ?? []);
+    if (target.kind === "archived") {
+        if (keepsArchived(target.repositoryId))
+            return { kind: "archived", repositoryId: target.repositoryId };
+        if (keepsAgents(target.repositoryId))
+            return { kind: "workspace", repositoryId: target.repositoryId };
+    }
+    else {
+        const agent = agents.find((entry) => entry.id === target.agentId);
+        if (agent && !isOperatorAgentArchived(agent)) {
+            const repositoryId = agent.repository.repositoryId;
+            const working = agents.filter((entry) => entry.repository.repositoryId === repositoryId && !isOperatorAgentArchived(entry) && !purged.has(entry.id));
+            if (working.length === 0 && keepsAgents(repositoryId))
+                return { kind: "workspace", repositoryId };
+        }
+    }
+    const rows = selectVisibleTuiAgentTreeRows(state);
+    const survives = (row) => {
+        if (row.kind === "agent")
+            return !purged.has(row.agentId);
+        if (row.kind === "archived")
+            return keepsArchived(row.repositoryId);
+        if (row.kind === "workspace")
+            return keepsAgents(row.repositoryId);
+        return true;
+    };
+    const current = selectedRowIndex(rows, state.view.selection);
+    const from = current < 0 ? 0 : current;
+    const next = rows.slice(from).find(survives) ?? rows.slice(0, from).reverse().find(survives);
+    return next ? rowSelection(next) : null;
+}
+/**
+ * Find the visible row a selection names.
+ * @param rows - Visible rows in tree order.
+ * @param selection - Selection the tree holds, which may name a row that is collapsed or hidden.
+ * @returns - The row's index, or -1 when no visible row is selected.
+ */
+function selectedRowIndex(rows, selection) {
+    return rows.findIndex((row) => JSON.stringify(rowSelection(row)) === JSON.stringify(selection));
+}
 /**
  * Report the selection one tree row stands for.
  * @param row - Row the operator moved onto.
@@ -611,8 +784,8 @@ function archiveStatusLabel(agent) {
             return "archived by operator";
         case "lifecycle":
             return agent.lifecycle;
-        case "workspace_removed":
-            return "workspace removed";
+        case "directory_removed":
+            return "directory removed";
     }
 }
 const TREE_STATE_COLUMN = 2;

package/dist/src/tui/app.js

@@ -6,7 +6,7 @@ import { AgentTree, AgentTreeOverlay, executeAgentTreeResult, reduceAgentTreeKey
 import { ActionRunOverlay, ActionsOverlay, reduceOperatorActionsKey, skillInstallTerminalSize, } from "./actions.js";
 import { Line, Overlay, PaneBar, Rule, VERTICAL_SCROLL_STYLE, useTuiModel } from "./chrome.js";
 import { AgentTrafficLog, MessageDetail, MessageOverlays, selectNewestTuiTraffic, stepTuiTrafficSelection, } from "./message-views.js";
-import { AGENT_TREE_COLUMNS, sidePaneWidths, MESSAGE_LOG_COLUMNS, PORTRAIT_BREAKPOINT_COLUMNS, agentColor, activeAgentCount, agentLogScope, brokerIndicator, COLLAPSED_LOG_ROWS, describeCommandOutcome, diagnosticColor, fitBarLeading, formatClock, formatDiagnostic, selectedMessage, selectMessageBodyRows, selectTuiTraffic, } from "./presentation.js";
+import { AGENT_TREE_COLUMNS, sidePaneWidths, MESSAGE_LOG_COLUMNS, PORTRAIT_BREAKPOINT_COLUMNS, agentColor, activeAgentCount, agentLogScope, brokerIndicator, COLLAPSED_LOG_ROWS, describeCommandOutcome, describeCommandTarget, diagnosticColor, fitBarLeading, formatClock, formatDiagnostic, selectedMessage, selectMessageBodyRows, selectTuiTraffic, } from "./presentation.js";
 import { dimTuiTheme } from "./theme.js";
 import { PAGER_VERSION } from "../version.js";
 /* eslint-enable jsdoc/require-jsdoc -- The collaborator declarations end here. */
@@ -143,6 +143,9 @@ export function OperatorTui(properties) {
         };
     }, [properties.model]);
     useKeyboard((key) => {
+        // A pane whose handler ran first marks a key it spent closing its own overlay.
+        if (key.defaultPrevented)
+            return;
         const current = properties.model.state;
         if (current.view.overlay.kind === "help" || current.view.overlay.kind === "log") {
             // The key that opened the log closes it, so it reads as a toggle rather than a one-way door.
@@ -357,8 +360,9 @@ function DividerCell({ theme, glyph }) {
 }
 function submitCommand(model, commands) {
     return (command) => {
+        const target = describeCommandTarget(model.state, command);
         const report = (result) => {
-            const outcome = describeCommandOutcome(model.state, command, result);
+            const outcome = describeCommandOutcome(target, command, result);
             model.reportDiagnostic(outcome.severity, "command", outcome.summary);
         };
         void model

package/dist/src/tui/message-views.js

@@ -4,7 +4,7 @@ import { useState } from "react";
 import { isTuiExpirable } from "../operator/agent-projection.js";
 import { OPERATOR_PROTOCOL_VERSION, } from "../operator/protocol.js";
 import { Line, Overlay, PaneBar, Rule, SCROLLBAR_RESERVED_COLUMNS, VERTICAL_SCROLL_STYLE, WRAPPED_TEXT_SCROLL_STYLE, fitOverlayColumns, useTuiModel, } from "./chrome.js";
-import { AGENT_TRAFFIC_COLUMNS, MESSAGE_LABEL_GUTTER, MINIMUM_MESSAGE_BODY_ROWS, MESSAGE_LOG_COLUMNS, SELECTION_GUTTER_GLYPH, WORKSPACE_TRAFFIC_COLUMNS, agentColor, agentHandle, agentAddress, agentLogScope, deliveryColor, deliveryGlyph, describeCommandOutcome, findTuiMessage, fitBarLeading, formatClock, formatClockSeconds, PANE_BAR_INSET_COLUMNS, padCells, padCellsBeforeColumn, padCellsEnd, selectedMessage, selectTuiTraffic, stepWrappingIndex, trafficSubject, trafficTime, trafficType, trafficTypeColumnWidth, truncateCells, } from "./presentation.js";
+import { AGENT_TRAFFIC_COLUMNS, MESSAGE_LABEL_GUTTER, MINIMUM_MESSAGE_BODY_ROWS, MESSAGE_LOG_COLUMNS, SELECTION_GUTTER_GLYPH, WORKSPACE_TRAFFIC_COLUMNS, agentColor, agentHandle, agentAddress, agentLogScope, deliveryColor, deliveryGlyph, describeCommandOutcome, describeCommandTarget, findTuiMessage, fitBarLeading, formatClock, formatClockSeconds, PANE_BAR_INSET_COLUMNS, padCells, padCellsBeforeColumn, padCellsEnd, selectedMessage, selectTuiTraffic, stepWrappingIndex, trafficSubject, trafficTime, trafficType, trafficTypeColumnWidth, truncateCells, } from "./presentation.js";
 /* eslint-enable jsdoc/require-jsdoc -- The port and property declarations end here. */
 /**
  * Render a distinct, renderer-neutral description for each traffic protocol member.
@@ -380,6 +380,7 @@ function ExpireConfirmOverlay({ model, theme, commands, message, }) {
  */
 async function submitExpiry(model, commands, messageId) {
     const command = { type: "expire_message", messageId };
+    const target = describeCommandTarget(model.state, command);
     let result;
     try {
         result = await model.execute({
@@ -390,11 +391,11 @@ async function submitExpiry(model, commands, messageId) {
         });
     }
     catch {
-        const outcome = describeCommandOutcome(model.state, command, null);
+        const outcome = describeCommandOutcome(target, command, null);
         model.reportDiagnostic(outcome.severity, "command", outcome.summary);
         return;
     }
-    const outcome = describeCommandOutcome(model.state, command, result);
+    const outcome = describeCommandOutcome(target, command, result);
     model.reportDiagnostic(outcome.severity, "command", outcome.summary);
     try {
         commands.observe(result);

package/dist/src/tui/model.d.ts

@@ -1,5 +1,5 @@
 import { type OperatorAgentHealth } from "../operator/agent-projection.js";
-import { type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCursor, type OperatorDiagnostic, type OperatorSnapshot, type OperatorTraffic } from "../operator/protocol.js";
+import { type OperatorAgent, type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCursor, type OperatorDiagnostic, type OperatorSnapshot, type OperatorTraffic } from "../operator/protocol.js";
 import type { AgentId } from "../broker/protocol.js";
 /** A renderer-neutral terminal pane. */
 export type TuiPane = "tree" | "agent_log" | "message_log";
@@ -37,9 +37,16 @@ export type TuiOverlay = {
     kind: "context_menu";
     target: "workspace";
     repositoryId: string;
+} | {
+    kind: "context_menu";
+    target: "archived";
+    repositoryId: string;
 } | {
     kind: "archive_confirm";
     agentId: AgentId;
+} | {
+    kind: "purge_confirm";
+    target: TuiPurgeTarget;
 } | {
     kind: "expire_confirm";
     messageId: string;
@@ -53,6 +60,23 @@ export type TuiOverlay = {
 } | {
     kind: "log";
 };
+/** What a purge confirmation would delete: one agent, or the agents one workspace's archive section held when it opened. */
+export type TuiPurgeTarget = {
+    kind: "agent";
+    agentId: AgentId;
+} | {
+    kind: "archived";
+    repositoryId: string;
+    agentIds: readonly AgentId[];
+};
+/**
+ * List the agents a purge confirmation still deletes.
+ * @param target - What the confirmation names.
+ * @param agents - Agents the current projection holds.
+ * @returns - The named agent while it is projected, or those the archive section held when the
+ * confirmation opened that are still archived in that workspace.
+ */
+export declare function selectTuiPurgeableAgents(target: TuiPurgeTarget, agents: readonly OperatorAgent[]): OperatorAgent[];
 /** Local operator state kept outside authoritative broker facts. */
 export type TuiOperatorViewState = {
     focus: TuiPane;

package/dist/src/tui/model.js

@@ -1,7 +1,20 @@
-import { archivedOperatorRepositoryIds, selectOperatorAgentHealth, } from "../operator/agent-projection.js";
+import { archivedOperatorRepositoryIds, isOperatorAgentArchived, selectOperatorAgentHealth, } from "../operator/agent-projection.js";
 import { OPERATOR_PROTOCOL_VERSION, } from "../operator/protocol.js";
 import { classifyOperatorEvent, validateOperatorSnapshot } from "../operator/validation.js";
 import { isTuiExpirable } from "../operator/agent-projection.js";
+/**
+ * List the agents a purge confirmation still deletes.
+ * @param target - What the confirmation names.
+ * @param agents - Agents the current projection holds.
+ * @returns - The named agent while it is projected, or those the archive section held when the
+ * confirmation opened that are still archived in that workspace.
+ */
+export function selectTuiPurgeableAgents(target, agents) {
+    if (target.kind === "agent")
+        return agents.filter((agent) => agent.id === target.agentId);
+    const named = new Set(target.agentIds);
+    return agents.filter((agent) => named.has(agent.id) && agent.repository.repositoryId === target.repositoryId && isOperatorAgentArchived(agent));
+}
 /* eslint-enable jsdoc/require-jsdoc -- The state field declarations end here. */
 /** Entries the diagnostics log keeps before discarding its oldest. */
 const TUI_DIAGNOSTIC_LIMIT = 200;
@@ -657,14 +670,19 @@ function reconcileView(view, snapshot, previous) {
     const messageIds = acceptedIds(snapshot.traffic);
     const trafficIds = new Set(snapshot.traffic.map((traffic) => traffic.trafficId));
     const hiddenRepositories = new Set([...view.hiddenRepositories].filter((id) => repositoryIds.has(id)));
-    const selection = selectionSurviving(view.selection, repositoryIds, agentIds, hiddenRepositories);
+    // A repository with no agent keeps its view state but has no row to select.
+    const occupied = new Set(snapshot.agents.map((agent) => agent.repository.repositoryId));
+    const sections = new Set(snapshot.agents.filter(isOperatorAgentArchived).map((agent) => agent.repository.repositoryId));
+    const selection = selectionSurviving(view.selection, occupied, sections, agentIds, new Set([...hiddenRepositories].filter((id) => occupied.has(id))));
     const trafficId = view.trafficId !== null && !trafficIds.has(view.trafficId) ? null : view.trafficId;
     return {
         ...view,
         selection,
         trafficId,
-        overlay: reconcileOverlay(view.overlay, repositoryIds, agentIds, messageIds, expirableIds(snapshot.traffic)),
-        collapsedRepositories: new Set([...collapsedRepositories].filter((id) => repositoryIds.has(id))),
+        overlay: reconcileOverlay(view.overlay, snapshot.agents, agentIds, occupied, sections, messageIds, expirableIds(snapshot.traffic)),
+        // An empty workspace's collapse is dropped, so one that was collapsed for being archived opens for
+        // the agent that next starts in it.
+        collapsedRepositories: new Set([...collapsedRepositories].filter((id) => occupied.has(id))),
         hiddenRepositories,
         archivedSections: new Map([...view.archivedSections].filter(([id]) => repositoryIds.has(id))),
     };
@@ -672,16 +690,18 @@ function reconcileView(view, snapshot, previous) {
 /**
  * Keep a tree selection only while the row it names can still be shown.
  * @param selection - Selection held before the projection changed.
- * @param repositoryIds - Repositories the new projection holds.
+ * @param repositoryIds - Repositories the new projection shows a row for.
+ * @param archivedSections - Repositories the new projection shows an archive section for.
  * @param agentIds - Agents the new projection holds.
- * @param hiddenRepositories - Hidden repositories that survive in the new projection; the hidden section exists only while any do.
+ * @param hiddenRepositories - Hidden repositories the new projection shows; the hidden section exists only while any do.
  * @returns The same selection, or null when its row is gone.
  */
-function selectionSurviving(selection, repositoryIds, agentIds, hiddenRepositories) {
+function selectionSurviving(selection, repositoryIds, archivedSections, agentIds, hiddenRepositories) {
     switch (selection?.kind) {
         case "workspace":
-        case "archived":
             return repositoryIds.has(selection.repositoryId) ? selection : null;
+        case "archived":
+            return archivedSections.has(selection.repositoryId) ? selection : null;
         case "agent":
             return agentIds.has(selection.agentId) ? selection : null;
         case "hidden":
@@ -693,13 +713,15 @@ function selectionSurviving(selection, repositoryIds, agentIds, hiddenRepositori
 function expirableIds(traffic) {
     return new Set(traffic.flatMap((entry) => (entry.kind === "accepted_delivery" && isTuiExpirable(entry) ? [entry.messageId] : [])));
 }
-function reconcileOverlay(overlay, repositoryIds, agentIds, messageIds, expirable) {
+function reconcileOverlay(overlay, agents, agentIds, repositoryIds, archivedSections, messageIds, expirable) {
     const closed = { kind: "none" };
     switch (overlay.kind) {
         case "agent_identity":
             return agentIds.has(overlay.agentId) ? overlay : closed;
         case "archive_confirm":
             return agentIds.has(overlay.agentId) ? overlay : closed;
+        case "purge_confirm":
+            return selectTuiPurgeableAgents(overlay.target, agents).length > 0 ? overlay : closed;
         case "full_message":
             return messageIds.has(overlay.messageId) ? overlay : closed;
         case "expire_confirm":
@@ -710,6 +732,8 @@ function reconcileOverlay(overlay, repositoryIds, agentIds, messageIds, expirabl
                 return agentIds.has(overlay.agentId) ? overlay : closed;
             if (overlay.target === "message")
                 return messageIds.has(overlay.messageId) ? overlay : closed;
+            if (overlay.target === "archived")
+                return archivedSections.has(overlay.repositoryId) ? overlay : closed;
             return repositoryIds.has(overlay.repositoryId) ? overlay : closed;
         case "none":
         case "actions":