@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/actions.js

@@ -0,0 +1,253 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@opentui/react/jsx-runtime";
+import { skillInstallCommand } from "../launch/skill.js";
+import { useKeyboard, useRenderer } from "@opentui/react";
+import { useState } from "react";
+import { Overlay, PaneBar, Rule } from "./chrome.js";
+import { copyRaw } from "./message-views.js";
+import { stepWrappingIndex } from "./presentation.js";
+import { RunTerminal } from "./run-terminal.js";
+/** Sizes the actions menu, which holds one short label per row. */
+const ACTIONS_OVERLAY_COLUMNS = 34;
+/**
+ * Sizes the confirmation overlay.
+ *
+ * Wide enough to show an indented absolute source path without wrapping.
+ */
+const ACTION_CONFIRM_OVERLAY_COLUMNS = 110;
+/**
+ * Installs into the global scope, leaving every other choice to the operator.
+ *
+ * The child runs in a terminal it can prompt through, so nothing here answers on the operator's
+ * behalf.
+ */
+export const SKILL_INSTALL_FLAGS = ["--global"];
+/** Stable empty buffer, so a terminal with no run yet does not see a new array on every render. */
+const NO_CHUNKS = [];
+/** Names every skill action in the menu. */
+export const SKILL_ACTION_LABEL = "Install skills";
+/** Footer keys of the actions menu. A constant, because JSX collapses runs of spaces in inline text. */
+export const ACTIONS_FOOTER_KEYS = "⏎ select";
+/** Columns the child's terminal is told it has, after the frame's border and the body's padding. */
+const RUN_TERMINAL_COLUMNS = ACTION_CONFIRM_OVERLAY_COLUMNS - 4;
+/** Overlay rows the frame, the pane bar, both rules, and the footer occupy, leaving the rest for content. */
+const RUN_OVERLAY_CHROME_ROWS = 6;
+/** Rows the run overlay leaves around itself, so the shell it covers is still visibly there. */
+const RUN_OVERLAY_MARGIN_ROWS = 4;
+/** Fewest rows the run overlay takes, below which a child has no room to draw a question. */
+const RUN_OVERLAY_MINIMUM_ROWS = 12;
+/** Most rows the run overlay takes, beyond which a child gains nothing from the extra height. */
+const RUN_OVERLAY_MAXIMUM_ROWS = 44;
+const NO_RUN_REQUEST = { kind: "none" };
+/**
+ * List the actions the operator may start from the menu, in display order.
+ *
+ * Declared as data so a further action is an entry here rather than a branch in the menu, which
+ * never names a specific action.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - Every selectable action, in display order.
+ */
+export function operatorActions(catalogue) {
+    return [
+        ...catalogue.skills.map((skill) => ({
+            id: `install_skill:${skill.name}`,
+            label: SKILL_ACTION_LABEL,
+            title: `install ${skill.name}`,
+            command: skillActionCommand(skill),
+        })),
+        ...catalogue.registrations.map((registration) => ({
+            id: `register_host:${registration.id}`,
+            label: "Install plugins",
+            title: `install ${registration.label} plugin`,
+            command: registration.command,
+        })),
+    ];
+}
+/**
+ * Build the command that installs one skill.
+ * @param skill - Skill the action installs.
+ * @returns - Command the action runs.
+ */
+function skillActionCommand(skill) {
+    const install = skillInstallCommand(SKILL_INSTALL_FLAGS, skill.source);
+    return { ...install, display: [install.command, ...install.args].join(" ") };
+}
+/**
+ * Find the action an overlay was opened for.
+ * @param id - Action id recorded when the action was selected.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - The action, or undefined when this build no longer offers one by that id.
+ */
+export function menuAction(id, catalogue) {
+    return operatorActions(catalogue).find((action) => action.id === id);
+}
+/**
+ * Reduce one key pressed while an action overlay is open.
+ *
+ * Pure. `y`, which copies the command before a run, is the one action-overlay key `ActionRunOverlay`
+ * answers itself.
+ *
+ * Escape during a run ends the child at once, without asking again, so the operator can always leave a
+ * run that will not finish, including an Escape the operator meant for a prompt of the child's own.
+ * @param state - Current model state.
+ * @param key - Key name reported by the terminal.
+ * @param catalogue - Skills and harness registrations this build offers.
+ * @returns - Next view state, unchanged when the key means nothing here, and the run request the key makes.
+ */
+export function reduceOperatorActionsKey(state, key, catalogue) {
+    const view = state.view;
+    const actions = operatorActions(catalogue);
+    const unchanged = { view, request: NO_RUN_REQUEST };
+    const close = () => ({
+        view: { ...view, focus: view.overlayReturnFocus, overlay: { kind: "none" }, actionIndex: 0 },
+        request: { kind: "clear" },
+    });
+    if (view.overlay.kind === "actions") {
+        if (key === "escape")
+            return close();
+        if (key === "up" || key === "down")
+            return {
+                view: { ...view, actionIndex: stepWrappingIndex(view.actionIndex, key, actions.length) },
+                request: NO_RUN_REQUEST,
+            };
+        if (key !== "enter" && key !== "return")
+            return unchanged;
+        const action = actions[view.actionIndex];
+        return action
+            ? { view: { ...view, overlay: { kind: "action_run", actionId: action.id } }, request: NO_RUN_REQUEST }
+            : unchanged;
+    }
+    const opened = view.overlay;
+    if (opened.kind !== "action_run")
+        return unchanged;
+    const action = menuAction(opened.actionId, catalogue);
+    if (!action)
+        return unchanged;
+    const running = state.run?.outcome.kind === "running";
+    // A key of its own to run again, so the one that closes the overlay never also repeats the command.
+    if (key === "r" && state.run !== null && !running)
+        return { view, request: { kind: "start", command: action.command } };
+    // The overlay stays open on the outcome of the run Escape ended, and the next Escape leaves.
+    if (key === "escape")
+        return running ? { view, request: { kind: "cancel" } } : close();
+    if (key !== "enter" && key !== "return")
+        return unchanged;
+    if (state.run === null)
+        return { view, request: { kind: "start", command: action.command } };
+    // Enter started the run, so the reflex press that dismisses a finished overlay must not repeat a
+    // command that writes to the operator's machine; `r` runs it again.
+    return running ? unchanged : close();
+}
+/**
+ * Render the operator actions menu.
+ * @param properties - Described on each property below.
+ * @returns Overlay centred over the shell, listing the packaged skills first and then each registration.
+ */
+export function ActionsOverlay({ actionIndex, catalogue, theme, onSelect, }) {
+    return (_jsxs(Overlay, { theme: theme, width: ACTIONS_OVERLAY_COLUMNS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "Menu" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), _jsx("box", { flexDirection: "column", children: operatorActions(catalogue).map((action, index) => (_jsx("box", { height: 1, paddingLeft: 1, paddingRight: 1, ...(index === actionIndex ? { backgroundColor: theme.structure.selection.background } : {}), onMouseDown: () => {
+                        onSelect(action);
+                    }, children: _jsx("text", { fg: index === actionIndex ? theme.structure.selection.text : theme.structure.bodyText, children: action.label }) }, action.id))) }), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: ACTIONS_FOOTER_KEYS }), right: null })] }));
+}
+/**
+ * Describe a run in the words the title bar uses.
+ * @param run - Current run, or null before one has started.
+ * @returns - Short status shown beside the overlay title.
+ */
+function skillInstallStatus(run) {
+    if (run === null)
+        return "ready";
+    const dropped = run.truncated ? "  earlier output dropped" : "";
+    switch (run.outcome.kind) {
+        case "running":
+            return run.truncated ? "running  earlier output dropped" : "running";
+        case "failed":
+            return `failed  ${run.outcome.reason}${dropped}`;
+        case "cancelled":
+            return `cancelled${dropped}`;
+        case "exited":
+            // "complete" says the command finished, not that everything it attempted worked: this CLI exits
+            // zero having reported some of its own installations as failed, so only its output says that.
+            return run.outcome.code === 0 ? `complete${dropped}` : `failed  exit ${String(run.outcome.code)}${dropped}`;
+    }
+}
+/**
+ * Describe the keys available in the words the footer uses.
+ * @param run - Current run, or null before one has started.
+ * @param copyStatus - Outcome of the operator's last copy, or null if they have not asked for one.
+ * @returns - Footer key hints for the run's current state.
+ */
+function skillInstallFooterKeys(run, copyStatus) {
+    // A running child holds every key the overlay would otherwise offer, apart from the one that ends it.
+    if (run?.outcome.kind === "running")
+        return "esc cancel";
+    if (run !== null)
+        return "⏎ close  r rerun";
+    if (copyStatus !== null)
+        return copyStatus === "unavailable" ? "copy unavailable" : "command copied";
+    return "⏎ run  y copy";
+}
+/**
+ * Colour the outcome so a clean exit and a failure read as such without being read. No run yet, a run
+ * still going, and a cancelled run share the neutral colour; only the status text tells them apart.
+ *
+ * Green marks a zero exit, which says the command finished and nothing more; see `skillInstallStatus`.
+ * @param run - Current run, or null before one has started.
+ * @param theme - Semantic palette the surface draws from.
+ * @returns - Colour for the status shown beside the title.
+ */
+export function skillInstallStatusColor(run, theme) {
+    if (run === null)
+        return theme.structure.rulesAndLabels;
+    switch (run.outcome.kind) {
+        case "running":
+        case "cancelled":
+            return theme.structure.rulesAndLabels;
+        case "failed":
+            return theme.states.failed;
+        case "exited":
+            return run.outcome.code === 0 ? theme.states.complete : theme.states.failed;
+    }
+}
+/**
+ * Report the terminal the install's child is given.
+ *
+ * The child lays its output out for this size, and the emulator that renders that output is built to
+ * match, so the two must be read from here rather than each deciding for itself.
+ * @param terminalRows - Rows the whole terminal has.
+ * @returns - Columns and rows of the run overlay's terminal.
+ */
+export function skillInstallTerminalSize(terminalRows) {
+    return { columns: RUN_TERMINAL_COLUMNS, rows: skillInstallOverlayRows(terminalRows) - RUN_OVERLAY_CHROME_ROWS };
+}
+/**
+ * Report how tall the run overlay is on a terminal of a given height.
+ *
+ * The child draws a question the operator has to answer, and a selection list shows only as many
+ * options as it has rows, so the overlay takes what the terminal can spare rather than a fixed size.
+ * @param terminalRows - Rows the whole terminal has.
+ * @returns - Rows the overlay occupies, including its frame.
+ */
+function skillInstallOverlayRows(terminalRows) {
+    const available = terminalRows - RUN_OVERLAY_MARGIN_ROWS;
+    return Math.max(RUN_OVERLAY_MINIMUM_ROWS, Math.min(RUN_OVERLAY_MAXIMUM_ROWS, available));
+}
+/**
+ * Render one action's run: its command, its terminal, its outcome, and the keys it answers.
+ * @param properties - Described on each property below.
+ * @returns The run overlay, or nothing when this build no longer offers the action.
+ */
+export function ActionRunOverlay({ run, actionId, catalogue, terminalRows, copyFallback, onInput, onResize, theme, }) {
+    const action = menuAction(actionId, catalogue);
+    const size = skillInstallTerminalSize(terminalRows);
+    const renderer = useRenderer();
+    const [copyStatus, setCopyStatus] = useState(null);
+    useKeyboard((key) => {
+        // Only before a run: once the command has been given a terminal here, copying it for another one
+        // has no purpose.
+        if (key.name !== "y" || run !== null || !action)
+            return;
+        setCopyStatus(copyRaw(renderer, action.command.display, copyFallback));
+    });
+    if (!action)
+        return null;
+    return (_jsxs(Overlay, { theme: theme, width: ACTION_CONFIRM_OVERLAY_COLUMNS, height: skillInstallOverlayRows(terminalRows), children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: action.title }), right: _jsx("text", { fg: skillInstallStatusColor(run, theme), children: skillInstallStatus(run) }) }), _jsx(Rule, { theme: theme }), _jsx("box", { flexDirection: "column", paddingLeft: 1, paddingRight: 1, children: _jsx(RunTerminal, { preamble: `$ ${action.command.display}\r\n`, chunks: run?.chunks ?? NO_CHUNKS, received: run?.received ?? 0, columns: size.columns, rows: size.rows, live: run?.outcome.kind === "running", dimmed: run !== null && run.outcome.kind !== "running", onInput: onInput, onResize: onResize }, run?.id ?? 0) }), _jsx(Rule, { theme: theme }), _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: skillInstallFooterKeys(run, copyStatus) }), right: null })] }));
+}

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

@@ -0,0 +1,125 @@
+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 { TuiTheme } from "./theme.js";
+/** Agent rows grouped by their projected repository without creating broker scope. */
+export type TuiRepositoryAgentGroup = {
+    /** Projected repository shown by this group. */
+    readonly repository: OperatorRepository;
+    /** Active agents in registration order. */
+    readonly active: readonly OperatorAgent[];
+    /** Agents `isOperatorAgentArchived` places in the archive section, in registration order. */
+    readonly archived: readonly OperatorAgent[];
+};
+/** One focusable action offered for a selected agent row. */
+export type TuiAgentContextAction = "ping" | "details" | "archive" | "collapse";
+/** One focusable action offered for a selected workspace row. */
+export type TuiWorkspaceContextAction = "hide" | "unhide";
+/** A keyboard-reachable projected tree row. */
+export type TuiAgentTreeRow = {
+    readonly kind: "workspace";
+    readonly repositoryId: string;
+} | {
+    readonly kind: "agent";
+    readonly agentId: AgentId;
+} | {
+    readonly kind: "archived";
+    readonly repositoryId: string;
+} | {
+    readonly kind: "hidden";
+};
+/** Supplies the agent-tree presentation with model state and command delegates. */
+export type AgentTreeProps = {
+    /** Renderer-independent state owner. */
+    readonly model: TuiOperatorModel;
+    /** Semantic terminal palette. */
+    readonly theme: Readonly<TuiTheme>;
+    /** Submits the broker command a tree action raised, a ping or an archive. */
+    readonly onCommand: (command: OperatorCommand) => void;
+    /** Enables terminal colours without changing textual distinctions. */
+    readonly colorEnabled?: boolean;
+    /** Character columns the pane gives the tree, including its one-column insets. */
+    readonly width?: number;
+};
+/**
+ * Group projected agents under their projected repositories in stable registration order.
+ * @param snapshot - Authoritative projection currently installed by the client model.
+ * @returns Repository groups suitable for the tree presentation.
+ */
+export declare function selectTuiRepositoryAgentGroups(snapshot: TuiOperatorModelState["snapshot"]): readonly TuiRepositoryAgentGroup[];
+/**
+ * Report whether one workspace's archive section is open: its stored preference, or else its default.
+ * @param view - Local view state holding the operator's archive preferences.
+ * @param group - Repository and its agents, already split by archive membership.
+ * @returns - Whether the section shows its agents.
+ */
+export declare function isTuiArchivedSectionOpen(view: TuiOperatorViewState, group: TuiRepositoryAgentGroup): boolean;
+/**
+ * Report whether a workspace is archived, which is to say every conversation in it is.
+ * @param group - Repository and its agents, already split by archive membership.
+ * @returns - Whether the workspace holds archived agents and no others.
+ */
+export declare function isArchivedGroup(group: TuiRepositoryAgentGroup): boolean;
+/**
+ * Select visible rows in tree order from model-owned expansion state.
+ * @param state - Current projection and local view state.
+ * @returns Rows available to keyboard navigation.
+ */
+export declare function selectVisibleTuiAgentTreeRows(state: TuiOperatorModelState): readonly TuiAgentTreeRow[];
+/**
+ * Report the workspace or archive section a tree selection can expand and collapse.
+ * @param state - Current authoritative projection and local presentation state.
+ * @returns The collapsible row's kind and repository, or null when the selection cannot collapse.
+ */
+export declare function selectTuiCollapsibleSelection(state: TuiOperatorModelState): {
+    readonly kind: "workspace" | "archived";
+    readonly repositoryId: string;
+} | null;
+/** The renderer-independent result of one tree keyboard command. */
+export type TuiAgentTreeKeyResult = {
+    /** Next model-owned presentation state. */
+    readonly view: TuiOperatorModelState["view"];
+    /** Broker-owned command this result asks the shell to submit. */
+    readonly command?: OperatorCommand;
+};
+/**
+ * Execute one already-reduced tree result through the model and broker delegate.
+ * @param model - Model that owns the local view state.
+ * @param onCommand - Submits a broker-owned command on the tree's behalf.
+ * @param result - Reducer result shared by keyboard and pointer actions.
+ */
+export declare function executeAgentTreeResult(model: TuiOperatorModel, onCommand: (command: OperatorCommand) => void, result: TuiAgentTreeKeyResult): void;
+/**
+ * Reduce a context-menu action for both keyboard and pointer activation.
+ * @param state - Current authoritative facts and local view state.
+ * @param action - Context action selected by the user.
+ * @returns The next local view and optional broker ping request.
+ */
+export declare function reduceAgentTreeContextAction(state: TuiOperatorModelState, action: TuiAgentContextAction): TuiAgentTreeKeyResult;
+/**
+ * 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.
+ */
+export declare function reduceAgentTreeKey(state: TuiOperatorModelState, key: string): TuiAgentTreeKeyResult;
+/**
+ * Render projected repositories, agents, archive sections, identity, and row actions.
+ * @param properties - Model, palette, and broker command delegate.
+ * @returns OpenTUI terminal presentation for the agent tree.
+ */
+export declare function AgentTree({ model, theme, onCommand, colorEnabled, width, }: AgentTreeProps): import("react").ReactNode;
+/**
+ * Render the tree-owned modal at the terminal root rather than inside the fixed pane.
+ * @param properties - Model state and palette shared with the agent-tree pane.
+ * @returns The overlay the tree owns for the current view state, or nothing when the open overlay is not the tree's.
+ */
+export declare function AgentTreeOverlay({ model, theme, onCommand, colorEnabled }: AgentTreeProps): import("react").ReactNode;
+/** Keys a row-action menu advertises in its footer. */
+export declare const CONTEXT_FOOTER_KEYS = "\u23CE select";
+/**
+ * List the actions offered for the workspace the menu was opened on.
+ * @param state - Current model state, holding what is hidden.
+ * @returns - The one action that applies, in a list so the menu never names a specific action.
+ */
+export declare function workspaceContextActions(state: TuiOperatorModelState): readonly TuiWorkspaceContextAction[];