@haywoodmarx/agent-pager 0.2.0 → 0.2.1

package/dist/src/operator/transport.js

@@ -3,9 +3,8 @@ import { StringDecoder } from "node:string_decoder";
 import { randomBytes } from "node:crypto";
 import { LOOPBACK_HOST } from "../configuration-defaults.js";
 import { closeServer, listenServer, urlHost } from "../shared/http.js";
-import { OPERATOR_PROTOCOL_VERSION, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./protocol.js";
+import { OPERATOR_PROTOCOL_VERSION, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES, } from "./protocol.js";
 import { OperatorValidationError, validateOperatorCommandResultForCommand, validateOperatorSnapshotByteLength, validateOperatorTransportRequest, } from "./validation.js";
-const INPUT_LIMIT_BYTES = 64 * 1_024;
 const LIVE_QUEUE_LIMIT = 32;
 const DIAGNOSTIC_LIMIT = 256;
 const DEFAULT_MAX_CONNECTIONS = 64;
@@ -214,10 +213,16 @@ class OperatorConnection {
         this.#socket.destroy();
     }
     #receive(chunk) {
-        if (this.#closed)
+        // A connection that is closing reads nothing more, so input from a peer that has stopped reading
+        // cannot pile up while its last frames wait to flush.
+        if (this.#closed || this.#closeAfterFlush) {
+            this.#buffer = "";
             return;
+        }
         this.#buffer += chunk;
-        if (Buffer.byteLength(this.#buffer, "utf8") > INPUT_LIMIT_BYTES) {
+        // One read can carry several whole requests, so only the unterminated one is measured here.
+        const unterminated = this.#buffer.slice(this.#buffer.lastIndexOf("\n") + 1);
+        if (Buffer.byteLength(unterminated, "utf8") > OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES) {
             this.#malformed();
             return;
         }
@@ -227,7 +232,7 @@ class OperatorConnection {
                 return;
             const line = this.#buffer.slice(0, newline);
             this.#buffer = this.#buffer.slice(newline + 1);
-            if (!line || Buffer.byteLength(line, "utf8") > INPUT_LIMIT_BYTES) {
+            if (!line || Buffer.byteLength(line, "utf8") > OPERATOR_TRANSPORT_REQUEST_LIMIT_BYTES) {
                 this.#malformed();
                 return;
             }

package/dist/src/operator/updates.js

@@ -8,7 +8,13 @@ const UPDATE_DIAGNOSTIC_LIMIT = 64;
 /** Broker tables whose rows feed the repository and agent halves of an operator snapshot. */
 const AGENT_SOURCE_TABLES = ["agents", "sessions", "workspaces", "alias_history"];
 /** Broker tables whose rows feed the traffic half of an operator snapshot. */
-const TRAFFIC_SOURCE_TABLES = ["messages", "message_events", "claims", "traffic_positions"];
+const TRAFFIC_SOURCE_TABLES = [
+    "messages",
+    "message_events",
+    "claims",
+    "traffic_positions",
+    "operator_ping_audits",
+];
 /** Produces complete snapshots and durable strictly ordered projection changes. */
 export class OperatorUpdateService {
     #source;

package/dist/src/operator/validation.js

@@ -1,4 +1,4 @@
-import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, } from "./protocol.js";
+import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_PURGE_TARGET_LIMIT, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, } from "./protocol.js";
 import { BROKER_OPERATOR_TRAFFIC_LIMIT, hasControlCharacter, isAgentId, isImplementationId, isOpaqueId, lifecycleEventState, MESSAGE_BODY_LIMIT_BYTES, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, } from "../broker/protocol.js";
 import { MESSAGE_STATES } from "../broker/schema.js";
 import { exactFields as guardExactFields, readArray as guardReadArray, readOwnEnumerableEntries as guardReadOwnEnumerableEntries, readRecord as guardReadRecord, } from "../shared/guards.js";
@@ -407,6 +407,22 @@ export function validateOperatorCommandResult(value) {
                 commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
                 acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
             };
+        case "purge_accepted":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "acceptedAt"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "accepted")
+                throw new OperatorValidationError("commandResult.status", "purge result must be accepted");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "purge_accepted",
+                status: "accepted",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
+            };
         case "command_rejected":
             exactFields({
                 record,
@@ -452,6 +468,10 @@ export function validateOperatorCommandResultForCommand(commandValue, resultValu
             if (result.type === "archive_accepted" || result.type === "command_rejected")
                 return { command: { ...command, command: command.command }, result };
             break;
+        case "purge_agents":
+            if (result.type === "purge_accepted" || result.type === "command_rejected")
+                return { command: { ...command, command: command.command }, result };
+            break;
     }
     throw new OperatorValidationError("commandResult.type", `${resultDescriptions[result.type]} cannot answer ${commandDescriptions[command.command.type]}`);
 }
@@ -708,11 +728,13 @@ const commandDescriptions = {
     ping_agent: "a ping command",
     expire_message: "an expiry command",
     archive_agent: "an archive command",
+    purge_agents: "a purge command",
 };
 const resultDescriptions = {
     ping_accepted: "ping acceptance",
     expiry_accepted: "expiry acceptance",
     archive_accepted: "archive acceptance",
+    purge_accepted: "purge acceptance",
     command_rejected: "rejection",
 };
 function validateCommandMember(value) {
@@ -727,6 +749,9 @@ function validateCommandMember(value) {
         case "archive_agent":
             exactFields({ record, required: ["type", "targetAgentId"], optional: [], path: "commandEnvelope.command" });
             return { type: "archive_agent", targetAgentId: readAgentId(record.targetAgentId, "command.targetAgentId") };
+        case "purge_agents":
+            exactFields({ record, required: ["type", "targetAgentIds"], optional: [], path: "commandEnvelope.command" });
+            return { type: "purge_agents", targetAgentIds: readPurgeTargets(record.targetAgentIds, "command.targetAgentIds") };
         default:
             throw new OperatorValidationError("commandEnvelope.command.type", "unknown command");
     }
@@ -858,6 +883,15 @@ function readAgentId(value, path) {
         throw new OperatorValidationError(path, "invalid agent identity");
     return id;
 }
+function readPurgeTargets(value, path) {
+    const entries = readArray(value, path);
+    if (entries.length === 0 || entries.length > OPERATOR_PURGE_TARGET_LIMIT)
+        throw new OperatorValidationError(path, "must name between one and the bounded number of agents");
+    const ids = entries.map((entry, index) => readAgentId(entry, `${path}[${String(index)}]`));
+    if (new Set(ids).size !== ids.length)
+        throw new OperatorValidationError(path, "must not repeat an agent");
+    return ids;
+}
 function readOpaqueId(value, path) {
     const id = readNonemptyString(value, path);
     if (!isOpaqueId(id))

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.

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;