@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/dist/src/tui/actions.js

@@ -0,0 +1,23 @@
+import { recoveryUnavailable } from "../recovery.js";
+/** Display eligibility only; the runner still validates command admission. */
+export function actionAvailability({ run, project, projectRuns, pending, }) {
+    const recoveryReason = run
+        ? (recoveryUnavailable(run) ??
+            project?.blocked ??
+            (projectRuns.some((item) => item.taskKey === run.taskKey && item.attempt > run.attempt)
+                ? "A newer attempt has superseded this run"
+                : undefined))
+        : undefined;
+    return {
+        recoveryReason,
+        available: {
+            stop: Boolean(run && !pending && ["queued", "running"].includes(run.outcome)),
+            retry: Boolean(run &&
+                !pending &&
+                ["failed", "blocked", "cancelled"].includes(run.outcome) &&
+                !projectRuns.some((item) => item.taskKey === run.taskKey &&
+                    ["queued", "running"].includes(item.outcome))),
+            recover: Boolean(run && !pending && !recoveryReason),
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+export declare const tuiRefreshIntervalMs = 400;
+export declare const minimumTerminalSize: {
+    readonly columns: 80;
+    readonly rows: 24;
+};
+export declare const screenChromeRows = 6;

package/dist/src/tui/constants.js

@@ -0,0 +1,3 @@
+export const tuiRefreshIntervalMs = 400;
+export const minimumTerminalSize = { columns: 80, rows: 24 };
+export const screenChromeRows = 6;

package/dist/src/{tui-data.d.ts → tui/data.d.ts}

@@ -1,5 +1,6 @@
-import type { RunRecord } from "./domain.js";
-import type { EventRecord, InvocationRecord, ProjectState, Store } from "./store.js";
+import type { RunRecord } from "../domain.js";
+import type { EventRecord, InvocationRecord, ProjectState, Store } from "../store.js";
+import { type ExecutionNotificationWriter } from "./notifications.js";
 export interface MonitorSource {
     projects: Store["projects"];
     runs: Store["runs"];
@@ -8,18 +9,20 @@ export interface MonitorSource {
     request: Store["request"];
     commands: Store["commands"];
 }
+export type MonitorAction = "pause" | "resume" | "stop" | "retry" | "recover";
 export declare function useMonitorData(source: MonitorSource, selection: {
-    projectIndex: number;
-    runIndex: number;
-}): {
+    projectId?: string;
+    runId?: string;
+}, notificationWriter?: ExecutionNotificationWriter): {
     projects: ProjectState[];
     project: ProjectState | undefined;
     projectRuns: RunRecord[];
     run: RunRecord | undefined;
     sessions: InvocationRecord[];
     events: EventRecord[];
+    connection: string;
+    lastUpdated: number | undefined;
     message: string;
-    setMessage: import("react").Dispatch<import("react").SetStateAction<string>>;
     pending: string | undefined;
-    action: (kind: "pause" | "resume" | "stop" | "retry", target: string) => Promise<void>;
+    action: (kind: MonitorAction, target: string) => Promise<void>;
 };

package/dist/src/tui/data.js

@@ -0,0 +1,146 @@
+import { useEffect, useRef, useState } from "react";
+import { tuiRefreshIntervalMs } from "./constants.js";
+import { ExecutionNotificationObserver, } from "./notifications.js";
+export function useMonitorData(source, selection, notificationWriter) {
+    const [projects, setProjects] = useState([]);
+    const [runs, setRuns] = useState([]);
+    const [detail, setDetail] = useState({ sessions: [], events: [] });
+    const [connection, setConnection] = useState("Connecting…");
+    const [lastUpdated, setLastUpdated] = useState();
+    const [message, setMessage] = useState("");
+    const [pending, setPending] = useState();
+    const pendingRef = useRef(undefined);
+    const mounted = useRef(true);
+    const notificationObserver = useRef(notificationWriter
+        ? new ExecutionNotificationObserver(notificationWriter)
+        : undefined).current;
+    const project = projects.find((item) => item.id === selection.projectId) ?? projects[0];
+    const projectRuns = runs.filter((item) => item.projectId === project?.id);
+    const run = projectRuns.find((item) => item.id === selection.runId) ?? projectRuns[0];
+    const selectedRunId = run?.id;
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    useEffect(() => {
+        let closed = false;
+        let busy = false;
+        let cursor = 0;
+        let history = [];
+        const update = async () => {
+            if (busy)
+                return;
+            busy = true;
+            try {
+                const [nextProjects, nextRuns] = await Promise.all([
+                    source.projects(),
+                    source.runs(),
+                ]);
+                if (closed)
+                    return;
+                setProjects(nextProjects);
+                setRuns(nextRuns);
+                notificationObserver?.observe(nextRuns);
+                if (selectedRunId) {
+                    const [sessions, nextEvents] = await Promise.all([
+                        source.invocations(selectedRunId),
+                        source.events(cursor, selectedRunId),
+                    ]);
+                    if (closed)
+                        return;
+                    const fresh = nextEvents.filter((event) => event.sequence > cursor);
+                    if (fresh.length)
+                        cursor = Math.max(...fresh.map((event) => event.sequence));
+                    history = [
+                        ...history,
+                        ...fresh.filter((event) => event.runId === selectedRunId && event.kind === "step"),
+                    ];
+                    setDetail({ runId: selectedRunId, sessions, events: history });
+                }
+                setConnection("Database connected");
+                setLastUpdated(Date.now());
+            }
+            catch (error) {
+                if (!closed)
+                    setConnection(`Connection error: ${String(error)}`);
+            }
+            finally {
+                busy = false;
+            }
+        };
+        void update();
+        const timer = setInterval(() => void update(), tuiRefreshIntervalMs);
+        return () => {
+            closed = true;
+            clearInterval(timer);
+        };
+    }, [source, selectedRunId, notificationObserver]);
+    useEffect(() => {
+        if (!pending || pending === "submitting")
+            return;
+        let closed = false;
+        let busy = false;
+        const update = async () => {
+            if (busy)
+                return;
+            busy = true;
+            try {
+                const command = (await source.commands()).find((item) => item.id === pending);
+                if (closed || !command || command.status === "pending")
+                    return;
+                setMessage(`${command.kind}: ${command.status}${command.error ? ` — ${command.error}` : ""}`);
+                pendingRef.current = undefined;
+                setPending(undefined);
+            }
+            catch (error) {
+                if (!closed)
+                    setMessage(`Command pending; cannot read acknowledgement: ${String(error)}`);
+            }
+            finally {
+                busy = false;
+            }
+        };
+        void update();
+        const timer = setInterval(() => void update(), tuiRefreshIntervalMs);
+        return () => {
+            closed = true;
+            clearInterval(timer);
+        };
+    }, [source, pending]);
+    const action = async (kind, target) => {
+        if (pendingRef.current)
+            return;
+        pendingRef.current = "submitting";
+        setPending("submitting");
+        setMessage(`${kind}: pending — waiting for runner`);
+        try {
+            const id = await source.request(kind, target);
+            if (!mounted.current)
+                return;
+            pendingRef.current = id;
+            setPending(id);
+        }
+        catch (error) {
+            if (!mounted.current)
+                return;
+            pendingRef.current = undefined;
+            setPending(undefined);
+            setMessage(`${kind}: submission failed — ${String(error)}`);
+        }
+    };
+    return {
+        projects,
+        project,
+        projectRuns,
+        run,
+        sessions: detail.runId === selectedRunId ? detail.sessions : [],
+        events: detail.runId === selectedRunId ? detail.events : [],
+        connection,
+        lastUpdated,
+        message,
+        pending,
+        action,
+    };
+}

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

@@ -0,0 +1,17 @@
+type DialogSize = {
+    columns: number;
+    rows: number;
+};
+export declare function HelpDialog({ columns, rows, onClose, initialPage, }: DialogSize & {
+    onClose: () => void;
+    initialPage?: number;
+}): import("react").JSX.Element;
+export declare function ConfirmDialog({ columns, rows, title, subject, description, available, onCancel, onConfirm, }: DialogSize & {
+    title: string;
+    subject: string;
+    description: string;
+    available: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+}): import("react").JSX.Element;
+export {};

package/dist/src/tui/dialogs.js

@@ -0,0 +1,149 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+import { colorFor, wrapLines } from "./format.js";
+import { Lines } from "./views.js";
+const dialogHorizontalMargin = 8;
+const dialogVerticalMargin = 4;
+const dialogContentWidthOffset = 6;
+const dialogChromeHeight = 11;
+function Dialog({ columns, rows, width, height, title, children, }) {
+    return (_jsx(Box, { width: columns, height: rows, justifyContent: "center", alignItems: "center", children: _jsxs(Box, { width: width, height: height, borderStyle: "round", borderColor: colorFor("running"), paddingX: 2, paddingY: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: title }), _jsx(Box, { height: 1, flexShrink: 0 }), children] }) }));
+}
+const helpPages = [
+    {
+        title: "Navigation",
+        rows: [
+            ["Tab", "Next pane"],
+            ["Shift+Tab", "Previous pane"],
+            ["↑ / ↓", "Select a run or session"],
+            ["← / →", "Select project"],
+            ["Enter", "Open run details"],
+            ["Esc", "Return from details"],
+            ["↑ / ↓", "Scroll summary or details"],
+            ["PgUp / PgDn", "Page through details"],
+            ["?", "Open keyboard shortcuts"],
+            ["q / Ctrl-C", "Close monitor; workflows continue"],
+        ],
+    },
+    {
+        title: "Workflow",
+        rows: [
+            ["p", "Pause or resume project intake"],
+            ["s", "Stop selected run"],
+            ["r", "Retry as a new run"],
+            ["c", "Recover failed publication"],
+            ["[ / ]", "Inspect previous or next step event"],
+            ["End", "Follow latest step event"],
+            ["a", "Focus agent sessions"],
+            ["l", "Open selected agent log"],
+            ["v", "Open validation logs"],
+        ],
+        note: "Stop, retry and recovery open a confirmation dialog.",
+    },
+    {
+        title: "Logs",
+        rows: [
+            ["↑ / ↓", "Scroll records"],
+            ["j / k", "Scroll down or up"],
+            ["PgUp / PgDn", "Scroll one page"],
+            ["← / →", "Pan long lines"],
+            ["Home / g", "Go to first page"],
+            ["End / G", "Go to last page"],
+            ["f", "Resume live follow"],
+            ["R", "Toggle readable or raw text"],
+            ["Tab", "Select next log"],
+            ["Esc", "Return to previous view"],
+        ],
+    },
+    {
+        title: "Search",
+        rows: [
+            ["/", "Start a literal search"],
+            ["Enter", "Apply search"],
+            ["n", "Next matching record"],
+            ["N", "Previous matching record"],
+            ["Esc", "Dismiss search before leaving logs"],
+        ],
+        note: "Search covers the whole selected log and wraps. Lowercase ignores case; uppercase makes it case-sensitive. Search pauses live follow.",
+    },
+    {
+        title: "Timing",
+        rows: [],
+        note: "Execution duration includes preparation and waits within one execution.\n\nQueue waiting and gaps before recovery are shown separately.\n\nDatabase connectivity does not establish runner liveness.",
+    },
+];
+export function HelpDialog({ columns, rows, onClose, initialPage = 0, }) {
+    const [page, setPage] = useState(initialPage);
+    const [offset, setOffset] = useState(0);
+    const width = Math.min(86, columns - dialogHorizontalMargin);
+    const height = Math.min(23, rows - dialogVerticalMargin);
+    const bodyHeight = height - dialogChromeHeight;
+    const current = helpPages[page];
+    const content = [
+        ...current.rows.map(([key, description]) => `${key.padEnd(17)}${description}`),
+        ...(current.note ? ["", current.note] : []),
+    ];
+    const maxOffset = Math.max(0, wrapLines(content, width - dialogContentWidthOffset).length - bodyHeight);
+    const changePage = (delta) => {
+        setPage((value) => (value + delta + helpPages.length) % helpPages.length);
+        setOffset(0);
+    };
+    useInput((input, key) => {
+        if (key.ctrl || key.meta || key.eventType === "release")
+            return;
+        if (key.escape || input === "?")
+            onClose();
+        else if (key.tab)
+            changePage(key.shift ? -1 : 1);
+        else if (key.leftArrow)
+            changePage(-1);
+        else if (key.rightArrow)
+            changePage(1);
+        else if (key.upArrow || key.pageUp)
+            setOffset((value) => Math.max(0, Math.min(value, maxOffset) - (key.pageUp ? bodyHeight : 1)));
+        else if (key.downArrow || key.pageDown)
+            setOffset((value) => Math.min(maxOffset, value + (key.pageDown ? bodyHeight : 1)));
+    });
+    return (_jsxs(Dialog, { columns: columns, rows: rows, width: width, height: height, title: "Keyboard shortcuts", children: [_jsx(Box, { gap: 1, children: helpPages.map((item, index) => (_jsxs(Text, { bold: index === page, inverse: index === page, children: [index === page ? ">" : "", item.title] }, item.title))) }), _jsx(Box, { height: 1, flexShrink: 0 }), _jsx(Lines, { lines: content, width: width - dialogContentWidthOffset, height: bodyHeight, offset: offset }), _jsx(Box, { height: 1, flexShrink: 0 }), _jsxs(Text, { dimColor: true, children: [page + 1, "/", helpPages.length, maxOffset
+                        ? ` · ↑↓ scroll (${Math.min(offset, maxOffset) + 1}/${maxOffset + 1})`
+                        : ""] }), _jsx(Text, { color: colorFor("running"), children: "Tab / \u2190\u2192 page \u00B7 Esc close" })] }));
+}
+export function ConfirmDialog({ columns, rows, title, subject, description, available, onCancel, onConfirm, }) {
+    const [selected, setSelected] = useState("cancel");
+    const [offset, setOffset] = useState(0);
+    const width = Math.min(78, columns - dialogHorizontalMargin);
+    const content = [
+        subject,
+        "",
+        description,
+        ...(!available
+            ? ["", "This action is no longer available. Cancel to refresh the view."]
+            : []),
+    ];
+    const contentLines = wrapLines(content, width - dialogContentWidthOffset).length;
+    const height = Math.min(rows - dialogVerticalMargin, contentLines + dialogChromeHeight);
+    const bodyHeight = height - dialogChromeHeight;
+    const maxOffset = Math.max(0, contentLines - bodyHeight);
+    useInput((input, key) => {
+        if (key.ctrl || key.meta || key.eventType === "release")
+            return;
+        if (key.escape || input === "n")
+            onCancel();
+        else if (key.tab || key.leftArrow || key.rightArrow)
+            setSelected((value) => (value === "cancel" ? "confirm" : "cancel"));
+        else if (key.return) {
+            if (selected === "cancel")
+                onCancel();
+            else if (available)
+                onConfirm();
+        }
+        else if (key.upArrow)
+            setOffset((value) => Math.max(0, Math.min(value, maxOffset) - 1));
+        else if (key.downArrow)
+            setOffset((value) => Math.min(maxOffset, value + 1));
+    });
+    return (_jsxs(Dialog, { columns: columns, rows: rows, width: width, height: height, title: title, children: [_jsx(Lines, { lines: content, width: width - dialogContentWidthOffset, height: bodyHeight, offset: offset }), _jsx(Box, { height: 1, flexShrink: 0 }), _jsxs(Box, { gap: 3, justifyContent: "flex-end", children: [_jsx(Text, { bold: selected === "cancel", inverse: selected === "cancel", children: selected === "cancel" ? "> Cancel " : "  Cancel " }), _jsxs(Text, { bold: selected === "confirm", inverse: selected === "confirm", dimColor: !available, children: [selected === "confirm" ? "> Confirm " : "  Confirm ", !available ? "(unavailable)" : ""] })] }), _jsx(Box, { height: 1, flexShrink: 0 }), _jsx(Text, { color: colorFor("running"), children: "Tab switch \u00B7 Enter select \u00B7 Esc cancel" }), _jsx(Text, { dimColor: true, children: maxOffset
+                    ? "↑↓ scroll message"
+                    : "Only Enter on Confirm submits the action." })] }));
+}

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

@@ -0,0 +1,7 @@
+import type { ExecutionRecord, RunRecord } from "../domain.js";
+export declare function duration(start?: string, end?: string, now?: number): string;
+export declare function executionDuration(execution: ExecutionRecord | undefined, now: number): string;
+export declare function elapsedRun(run: RunRecord, now: number): string;
+export declare function colorFor(outcome: string): string | undefined;
+export declare function cells(text: string, width: number, offset?: number): string;
+export declare function wrapLines(lines: string[], width: number): string[];

package/dist/src/tui/format.js

@@ -0,0 +1,62 @@
+import stringWidth from "string-width";
+import wrapAnsi from "wrap-ansi";
+import { terminalText } from "./text.js";
+const millisecondsPerSecond = 1_000;
+const secondsPerMinute = 60;
+const secondsPerHour = 60 * secondsPerMinute;
+const secondsPerDay = 24 * secondsPerHour;
+export function duration(start, end, now = Date.now()) {
+    if (!start || !Number.isFinite(Date.parse(start)))
+        return "—";
+    const finish = end ? Date.parse(end) : now;
+    if (!Number.isFinite(finish))
+        return "—";
+    const seconds = Math.max(0, Math.floor((finish - Date.parse(start)) / millisecondsPerSecond));
+    const days = Math.floor(seconds / secondsPerDay);
+    const hours = Math.floor((seconds % secondsPerDay) / secondsPerHour);
+    const minutes = Math.floor((seconds % secondsPerHour) / secondsPerMinute);
+    return `${days ? `${days}d ` : ""}${hours ? `${hours}h ` : ""}${minutes}m ${seconds % secondsPerMinute}s`;
+}
+export function executionDuration(execution, now) {
+    if (!execution ||
+        (!execution.finishedAt &&
+            !["queued", "running"].includes(execution.outcome)))
+        return "—";
+    return duration(execution.startedAt, execution.finishedAt, now);
+}
+export function elapsedRun(run, now) {
+    const latest = run.executions?.at(-1);
+    if (!["queued", "running"].includes(run.outcome) && !latest?.finishedAt)
+        return "—";
+    return duration(run.createdAt, latest?.finishedAt, now);
+}
+export function colorFor(outcome) {
+    if (process.env.NO_COLOR || process.env.TERM === "dumb")
+        return undefined;
+    if (["failed", "cancelled"].includes(outcome))
+        return "red";
+    if (["blocked", "queued"].includes(outcome))
+        return "yellow";
+    if (["completed", "no-change"].includes(outcome))
+        return "green";
+    return "cyan";
+}
+export function cells(text, width, offset = 0) {
+    let result = "";
+    let position = 0;
+    for (const { segment } of new Intl.Segmenter().segment(terminalText(text).replaceAll("\n", " ").replaceAll("\t", "    "))) {
+        const size = stringWidth(segment);
+        if (position >= offset && position + size <= offset + width)
+            result += segment;
+        position += size;
+        if (position >= offset + width)
+            break;
+    }
+    return result;
+}
+export function wrapLines(lines, width) {
+    return lines.flatMap((line) => wrapAnsi(terminalText(line).replaceAll("\t", "    "), Math.max(1, width), {
+        hard: true,
+        trim: false,
+    }).split("\n"));
+}

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

@@ -0,0 +1,3 @@
+export type { MonitorSource } from "./data.js";
+export { Monitor } from "./monitor.js";
+export { createTerminalNotificationWriter, type ExecutionNotification, type ExecutionNotificationWriter, } from "./notifications.js";

package/dist/src/tui/index.js

@@ -0,0 +1,2 @@
+export { Monitor } from "./monitor.js";
+export { createTerminalNotificationWriter, } from "./notifications.js";

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

@@ -0,0 +1,25 @@
+/** Pane content sizes shared by rendering and keyboard scrolling. */
+export declare function monitorLayout(columns: number, rows: number, compactChrome?: boolean): {
+    wide: boolean;
+    height: number;
+    paneWidth: number;
+    summaryWidth: number;
+    summaryPanelHeight: number;
+    sessionsPanelHeight: number;
+    details: {
+        width: number;
+        height: number;
+    };
+    runs: {
+        width: number;
+        height: number;
+    };
+    summary: {
+        width: number;
+        height: number;
+    };
+    sessions: {
+        width: number;
+        height: number;
+    };
+};

package/dist/src/tui/layout.js

@@ -0,0 +1,36 @@
+import { screenChromeRows } from "./constants.js";
+const panelHorizontalChrome = 4;
+const panelVerticalChrome = 3;
+/** Pane content sizes shared by rendering and keyboard scrolling. */
+export function monitorLayout(columns, rows, compactChrome = false) {
+    const wide = columns >= 110;
+    const height = Math.max(1, rows - (compactChrome ? 4 : screenChromeRows));
+    const paneWidth = wide ? Math.floor(columns * 0.43) : columns;
+    const summaryWidth = wide ? columns - paneWidth : columns;
+    const summaryPanelHeight = wide ? height - 6 : height;
+    const sessionsPanelHeight = wide ? 6 : height;
+    return {
+        wide,
+        height,
+        paneWidth,
+        summaryWidth,
+        summaryPanelHeight,
+        sessionsPanelHeight,
+        details: {
+            width: columns - panelHorizontalChrome,
+            height: height - panelVerticalChrome,
+        },
+        runs: {
+            width: paneWidth - panelHorizontalChrome,
+            height: height - panelVerticalChrome,
+        },
+        summary: {
+            width: summaryWidth - panelHorizontalChrome,
+            height: summaryPanelHeight - panelVerticalChrome,
+        },
+        sessions: {
+            width: summaryWidth - panelHorizontalChrome,
+            height: sessionsPanelHeight - panelVerticalChrome,
+        },
+    };
+}

package/dist/src/tui/log-file.d.ts

@@ -0,0 +1,26 @@
+export declare function presentLogLine(line: string, raw: boolean): string;
+/** Sparse byte offsets index the file; only requested pages hold decoded text. */
+export declare class LogFile {
+    readonly path: string;
+    private checkpoints;
+    private size;
+    private completeLines;
+    private tail;
+    private identity;
+    private modified;
+    revision: number;
+    private refreshTask;
+    constructor(path: string);
+    get count(): number;
+    refresh(signal: AbortSignal): Promise<void>;
+    private updateIndex;
+    private lines;
+    page(start: number, count: number, signal: AbortSignal): Promise<string[]>;
+    search(options: {
+        query: string;
+        from: number;
+        direction: 1 | -1;
+        raw: boolean;
+        signal: AbortSignal;
+    }): Promise<number | undefined>;
+}