@mingchuno/agent-workflows 0.2.0 → 0.4.0

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

@@ -1,2 +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

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

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

@@ -1,5 +1,5 @@
 /** Pane content sizes shared by rendering and keyboard scrolling. */
-export declare function monitorLayout(columns: number, rows: number): {
+export declare function monitorLayout(columns: number, rows: number, compactChrome?: boolean): {
     wide: boolean;
     height: number;
     paneWidth: number;

package/dist/src/tui/layout.js

@@ -2,9 +2,9 @@ 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) {
+export function monitorLayout(columns, rows, compactChrome = false) {
     const wide = columns >= 110;
-    const height = Math.max(1, rows - screenChromeRows);
+    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;

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

@@ -1,8 +1,10 @@
 import { type MonitorSource } from "./data.js";
-export declare function Monitor({ source, size, }: {
+import type { ExecutionNotificationWriter } from "./notifications.js";
+export declare function Monitor({ source, size, notificationWriter, }: {
     source: MonitorSource;
     size?: {
         columns: number;
         rows: number;
     };
+    notificationWriter?: ExecutionNotificationWriter;
 }): import("react").JSX.Element;

package/dist/src/tui/monitor.js

@@ -8,7 +8,8 @@ import { ConfirmDialog, HelpDialog } from "./dialogs.js";
 import { cells, colorFor, wrapLines } from "./format.js";
 import { monitorLayout } from "./layout.js";
 import { LogViewer } from "./log.js";
-import { detailLines, Lines, RunList, summaryLines } from "./views.js";
+import { detailLines, Lines, RunList, summaryLines, wrapDetailLines, } from "./views.js";
+const notificationNoticeDurationMs = 2000;
 const focuses = ["runs", "summary", "sessions"];
 const statusRefreshIntervalMs = 1_000;
 const actionDescriptions = {
@@ -16,12 +17,35 @@ const actionDescriptions = {
     retry: "Create a new run and branch; execute the workflow again.",
     recover: "Continue the failed publication step using completed work.",
 };
-export function Monitor({ source, size, }) {
+function currentExecutionSessions(run, sessions, events) {
+    const current = run?.executions?.at(-1);
+    if (!current || (run?.executions?.length ?? 0) <= 1)
+        return sessions;
+    const currentStepIds = new Set(events.flatMap((event) => {
+        const payload = event.payload;
+        return payload.executionId === current.id &&
+            typeof payload.stepId === "number"
+            ? [payload.stepId]
+            : [];
+    }));
+    if (currentStepIds.size)
+        return sessions.filter((item) => currentStepIds.has(item.stepId));
+    const executionCreatedAt = Date.parse(current.createdAt);
+    if (!Number.isFinite(executionCreatedAt))
+        return [];
+    return sessions.filter((item) => Date.parse(item.startedAt) >= executionCreatedAt);
+}
+function latestSession(sessions) {
+    const byRecency = [...sessions].sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
+    return (byRecency.filter((item) => item.outcome === "running").at(-1) ??
+        byRecency.at(-1));
+}
+export function Monitor({ source, size, notificationWriter, }) {
     const window = useWindowSize();
     const { columns, rows } = size ?? window;
     const { exit } = useApp();
     const [selection, setSelection] = useState({});
-    const data = useMonitorData(source, selection);
+    const data = useMonitorData(source, selection, notificationWriter);
     const { projects, project, projectRuns, run, sessions, events } = data;
     const [focus, setFocus] = useState("runs");
     const [screen, setScreen] = useState("dashboard");
@@ -32,9 +56,13 @@ export function Monitor({ source, size, }) {
     const [confirmation, setConfirmation] = useState();
     const [logs, setLogs] = useState();
     const [now, setNow] = useState(Date.now());
-    const layout = monitorLayout(columns, rows);
+    const [notificationNoticeUntil] = useState(() => Date.now() + notificationNoticeDurationMs);
+    const showNotificationNotice = Boolean(notificationWriter) && now < notificationNoticeUntil;
+    const layout = monitorLayout(columns, rows - (showNotificationNotice ? 1 : 0), screen === "details");
     const { wide, height, paneWidth, summaryWidth } = layout;
     const session = sessions.find((item) => item.id === sessionId) ?? sessions[0];
+    const executionSessions = currentExecutionSessions(run, sessions, events);
+    const detailLogSession = latestSession(executionSessions);
     const event = events.find((item) => item.sequence === stepSequence) ?? events.at(-1);
     useEffect(() => {
         const timer = setInterval(() => setNow(Date.now()), statusRefreshIntervalMs);
@@ -60,15 +88,15 @@ export function Monitor({ source, size, }) {
         setFocus("runs");
         setOffset(0);
     };
-    const openAgentLog = () => {
-        if (!sessions.length)
+    const openAgentLog = (candidates = sessions, initialSession = session) => {
+        if (!candidates.length)
             return;
         setLogs({
-            sources: sessions.map((item) => ({
+            sources: candidates.map((item) => ({
                 path: item.log,
                 label: `${item.step} · invocation ${item.attempt}`,
             })),
-            initial: Math.max(0, sessions.findIndex((item) => item.id === session?.id)),
+            initial: Math.max(0, candidates.findIndex((item) => item.id === initialSession?.id)),
         });
     };
     const { recoveryReason, available } = actionAvailability({
@@ -77,6 +105,11 @@ export function Monitor({ source, size, }) {
         projectRuns,
         pending: Boolean(data.pending),
     });
+    const detailDocument = run
+        ? detailLines(run, sessions, now, recoveryReason, layout.details.width, available)
+        : ["Run no longer available"];
+    const wrappedDetailLines = wrapDetailLines(detailDocument, layout.details.width);
+    const detailOffset = Math.min(offset, Math.max(0, wrappedDetailLines.length - layout.details.height));
     useInput((input, key) => {
         if (key.ctrl || key.meta || key.eventType === "release")
             return;
@@ -106,7 +139,7 @@ export function Monitor({ source, size, }) {
             setFocus(focuses[(focuses.indexOf(focus) + (key.shift ? 2 : 1)) % 3]);
             setOffset(0);
         }
-        if (input === "a") {
+        if (input === "a" && screen === "dashboard") {
             setScreen("dashboard");
             setFocus("sessions");
         }
@@ -114,12 +147,14 @@ export function Monitor({ source, size, }) {
             selectProject(-1);
         if (key.rightArrow && screen === "dashboard")
             selectProject(1);
-        if (key.return && run) {
+        if (key.return && run && screen === "dashboard") {
             setScreen("details");
             setOffset(0);
         }
         if (input === "l")
-            openAgentLog();
+            screen === "details"
+                ? openAgentLog(executionSessions, detailLogSession)
+                : openAgentLog();
         if (input === "v" && run?.validation?.length)
             setLogs({
                 sources: run.validation.map((item) => ({
@@ -128,24 +163,30 @@ export function Monitor({ source, size, }) {
                 })),
                 initial: 0,
             });
-        if (input === "[" || input === "]") {
+        if (screen === "dashboard" && (input === "[" || input === "]")) {
             const index = events.findIndex((item) => item.sequence === event?.sequence);
             setStepSequence(events[Math.max(0, Math.min(events.length - 1, index + (input === "]" ? 1 : -1)))]?.sequence);
         }
-        if (key.end)
+        if (key.end && screen === "dashboard")
             setStepSequence(undefined);
         if (key.upArrow || key.downArrow || key.pageUp || key.pageDown) {
             const delta = key.upArrow || key.pageUp ? -1 : 1;
             if (screen === "details" || focus === "summary") {
                 const lines = run
                     ? screen === "details"
-                        ? detailLines(run, sessions, now, recoveryReason)
+                        ? detailDocument
                         : summaryLines(run, now, event)
                     : [];
                 const viewport = screen === "details" ? layout.details : layout.summary;
-                setOffset((value) => Math.max(0, Math.min(wrapLines(lines, viewport.width).length - viewport.height, value +
-                    delta *
-                        (key.pageUp || key.pageDown ? layout.details.height : 1))));
+                setOffset((value) => {
+                    const maximum = Math.max(0, (screen === "details"
+                        ? wrapDetailLines(lines, viewport.width)
+                        : wrapLines(lines, viewport.width)).length - viewport.height);
+                    const current = screen === "details" ? Math.min(value, maximum) : value;
+                    return Math.max(0, Math.min(maximum, current +
+                        delta *
+                            (key.pageUp || key.pageDown ? layout.details.height : 1)));
+                });
             }
             else if (focus === "sessions") {
                 const index = sessions.findIndex((item) => item.id === session?.id);
@@ -160,7 +201,7 @@ export function Monitor({ source, size, }) {
                 });
             }
         }
-        if (input === "p" && project && !data.pending)
+        if (input === "p" && screen === "dashboard" && project && !data.pending)
             void data.action(project.paused ? "resume" : "pause", project.id);
         const kind = input === "s"
             ? "stop"
@@ -187,17 +228,33 @@ export function Monitor({ source, size, }) {
             } }));
     if (logs)
         return (_jsx(LogViewer, { ...logs, columns: columns, rows: rows, onBack: () => setLogs(undefined) }));
-    const status = `${data.connection}${data.lastUpdated ? ` · refreshed ${Math.max(0, Math.floor((now - data.lastUpdated) / statusRefreshIntervalMs))}s ago` : ""}`;
+    const freshness = data.lastUpdated
+        ? `refreshed ${Math.max(0, Math.floor((now - data.lastUpdated) / statusRefreshIntervalMs))}s ago`
+        : "freshness unavailable";
+    const status = `${data.connection} · ${freshness}`;
     const sessionIndex = Math.max(0, sessions.findIndex((item) => item.id === session?.id));
     const sessionLines = sessions.length
         ? sessions
             .slice(Math.max(0, sessionIndex - 1), sessionIndex + 3)
             .map((item) => `${item.id === session?.id ? ">" : " "} ${item.step} · invocation ${item.attempt} · ${item.outcome}`)
         : ["No agent sessions recorded"];
+    const detailsLogControl = detailLogSession
+        ? columns < 120
+            ? "l current log"
+            : `l log: ${detailLogSession.step} invocation ${detailLogSession.attempt} (${detailLogSession.outcome})`
+        : "";
     const controls = [
-        sessions.length ? "l log" : "",
-        run?.validation?.length ? "v validation" : "",
-        project ? (project.paused ? "p resume" : "p pause") : "",
+        screen === "details" ? detailsLogControl : sessions.length ? "l log" : "",
+        run?.validation?.length
+            ? columns < 120
+                ? "v checks"
+                : "v validation"
+            : "",
+        screen === "dashboard" && project
+            ? project.paused
+                ? "p resume"
+                : "p pause"
+            : "",
         available.stop ? "s stop" : "",
         available.retry ? "r retry" : "",
         available.recover ? "c recover" : "",
@@ -208,15 +265,20 @@ export function Monitor({ source, size, }) {
         .join(" · ");
     return (_jsxs(Box, { width: columns, height: rows, flexDirection: "column", children: [_jsx(Text, { bold: true, color: colorFor("running"), wrap: "truncate", children: cells(`Agent Workflows · ${screen === "dashboard" ? "Monitor" : "Run details"}`, columns) }), _jsx(Text, { wrap: "truncate", children: cells(project
                     ? `${project.id} · intake ${project.paused ? "paused" : "enabled"} · ${projectRuns.filter((item) => item.outcome === "queued").length} queued${project.blocked ? ` · BLOCKED: ${project.blocked}` : ""}`
-                    : "No projects registered. Start the runner to populate this view.", columns) }), _jsx(Box, { height: height, flexDirection: "row", overflow: "hidden", children: screen === "details" ? (_jsxs(Box, { borderStyle: "round", width: columns, height: height, paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Details \u00B7 \u2191\u2193 scroll \u00B7 Esc back" }), _jsx(Lines, { lines: run
-                                ? detailLines(run, sessions, now, recoveryReason)
-                                : ["Run no longer available"], width: layout.details.width, height: layout.details.height, offset: offset })] })) : (_jsxs(_Fragment, { children: [(wide || focus === "runs") && (_jsxs(Box, { width: paneWidth, height: height, borderStyle: "round", borderColor: focus === "runs" ? colorFor("running") : undefined, flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { bold: true, children: [focus === "runs" ? "> " : "", "Runs \u00B7 ", projectRuns.length] }), _jsx(RunList, { runs: projectRuns, selected: run?.id, width: layout.runs.width, height: layout.runs.height, now: now })] })), (wide || focus !== "runs") && (_jsxs(Box, { width: summaryWidth, height: height, flexDirection: "column", children: [(wide || focus === "summary") && (_jsxs(Box, { width: summaryWidth, height: layout.summaryPanelHeight, borderStyle: "round", borderColor: focus === "summary" ? colorFor("running") : undefined, paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [focus === "summary" ? "> " : "", "Summary \u00B7 Enter details"] }), _jsx(Lines, { lines: run
+                    : "No projects registered. Start the runner to populate this view.", columns) }), _jsx(Box, { height: height, flexDirection: "row", overflow: "hidden", children: screen === "details" ? (_jsxs(Box, { borderStyle: "round", width: columns, height: height, paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: wrappedDetailLines.length > layout.details.height
+                                ? `Details · lines ${detailOffset + 1}–${Math.min(detailOffset + layout.details.height, wrappedDetailLines.length)} of ${wrappedDetailLines.length}`
+                                : "Details" }), _jsx(Lines, { lines: detailDocument, width: layout.details.width, height: layout.details.height, offset: detailOffset, outcome: run?.outcome })] })) : (_jsxs(_Fragment, { children: [(wide || focus === "runs") && (_jsxs(Box, { width: paneWidth, height: height, borderStyle: "round", borderColor: focus === "runs" ? colorFor("running") : undefined, flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { bold: true, children: [focus === "runs" ? "> " : "", "Runs \u00B7 ", projectRuns.length] }), _jsx(RunList, { runs: projectRuns, selected: run?.id, width: layout.runs.width, height: layout.runs.height, now: now })] })), (wide || focus !== "runs") && (_jsxs(Box, { width: summaryWidth, height: height, flexDirection: "column", children: [(wide || focus === "summary") && (_jsxs(Box, { width: summaryWidth, height: layout.summaryPanelHeight, borderStyle: "round", borderColor: focus === "summary" ? colorFor("running") : undefined, paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [focus === "summary" ? "> " : "", "Summary \u00B7 Enter details"] }), _jsx(Lines, { lines: run
                                                 ? summaryLines(run, now, event)
-                                                : ["Select a run to inspect progress"], width: layout.summary.width, height: layout.summary.height, offset: offset })] })), (wide || focus === "sessions") && (_jsxs(Box, { width: summaryWidth, height: layout.sessionsPanelHeight, borderStyle: "round", borderColor: focus === "sessions" ? colorFor("running") : undefined, paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [focus === "sessions" ? "> " : "", "Agent sessions \u00B7", " ", sessions.length, " \u00B7 l log"] }), _jsx(Lines, { lines: sessionLines, width: layout.sessions.width, height: layout.sessions.height })] }))] }))] })) }), _jsx(Text, { wrap: "truncate", color: data.connection.startsWith("Connection error")
+                                                : ["Select a run to inspect progress"], width: layout.summary.width, height: layout.summary.height, offset: offset })] })), (wide || focus === "sessions") && (_jsxs(Box, { width: summaryWidth, height: layout.sessionsPanelHeight, borderStyle: "round", borderColor: focus === "sessions" ? colorFor("running") : undefined, paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [focus === "sessions" ? "> " : "", "Agent sessions \u00B7", " ", sessions.length, " \u00B7 l log"] }), _jsx(Lines, { lines: sessionLines, width: layout.sessions.width, height: layout.sessions.height })] }))] }))] })) }), showNotificationNotice && (_jsx(Text, { color: colorFor("running"), wrap: "truncate", children: cells("Notifications enabled; delivery is best-effort and depends on terminal settings", columns) })), _jsx(Text, { wrap: "truncate", color: data.connection.startsWith("Connection error")
                     ? colorFor("failed")
-                    : undefined, children: cells(data.message || status, columns) }), _jsx(Text, { dimColor: true, wrap: "truncate", children: cells(data.message
-                    ? status
-                    : "Runner liveness unverified · closing monitor leaves workflows running", columns) }), _jsx(Text, { color: colorFor("running"), wrap: "truncate", children: cells(screen === "dashboard"
-                    ? "Tab pane · ↑↓ select/scroll · ←→ project · Enter details"
-                    : "↑↓ scroll · PgUp/PgDn page · Esc back", columns) }), _jsx(Text, { wrap: "truncate", children: cells(controls, columns) })] }));
+                    : undefined, children: cells(`${data.message ? `${data.message} · ` : ""}${columns < 120 ? status.replace("Database ", "DB ") : status} · runner liveness unverified · closing leaves workflows running`, columns) }), _jsx(Text, { color: colorFor("running"), wrap: "truncate", children: cells([
+                    screen === "dashboard"
+                        ? "Tab pane · ↑↓ select/scroll · ←→ project · Enter details"
+                        : columns < 120
+                            ? "↑↓/Pg · Esc"
+                            : "↑↓ scroll · PgUp/PgDn page · Esc back",
+                    controls,
+                ]
+                    .filter(Boolean)
+                    .join(" · "), columns) })] }));
 }

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

@@ -0,0 +1,23 @@
+import type { RunRecord } from "../domain.js";
+declare const terminalOutcomes: readonly ["completed", "failed", "blocked", "cancelled", "no-change", "ineligible"];
+export type TerminalOutcome = (typeof terminalOutcomes)[number];
+export interface ExecutionNotification {
+    project: string;
+    issue: string;
+    outcome: TerminalOutcome;
+}
+export interface ExecutionNotificationWriter {
+    notify(notification: ExecutionNotification): void;
+}
+export declare class ExecutionNotificationObserver {
+    private readonly writer;
+    private seeded;
+    private readonly observedTerminalExecutionIds;
+    constructor(writer: ExecutionNotificationWriter);
+    observe(runs: RunRecord[]): void;
+}
+export declare function createTerminalNotificationWriter({ write, tmux, }?: {
+    write?: (value: string) => void | Promise<void>;
+    tmux?: boolean;
+}): ExecutionNotificationWriter;
+export {};

package/dist/src/tui/notifications.js

@@ -0,0 +1,104 @@
+import { write as writeFileDescriptor } from "node:fs";
+const terminalOutcomes = [
+    "completed",
+    "failed",
+    "blocked",
+    "cancelled",
+    "no-change",
+    "ineligible",
+];
+const terminalOutcomeSet = new Set(terminalOutcomes);
+const whitespace = /\s+/gu;
+const maximumPayloadBytes = 256;
+const notificationPrefix = "agent-workflows: ";
+export class ExecutionNotificationObserver {
+    writer;
+    seeded = false;
+    observedTerminalExecutionIds = new Set();
+    constructor(writer) {
+        this.writer = writer;
+    }
+    observe(runs) {
+        for (const run of runs) {
+            for (const execution of run.executions ?? []) {
+                if (!this.seeded) {
+                    if (isTerminal(execution.outcome))
+                        this.observedTerminalExecutionIds.add(execution.id);
+                    continue;
+                }
+                if (this.observedTerminalExecutionIds.has(execution.id) ||
+                    !isTerminal(execution.outcome))
+                    continue;
+                this.observedTerminalExecutionIds.add(execution.id);
+                try {
+                    this.writer.notify({
+                        project: run.projectId,
+                        issue: `#${run.issue.number}`,
+                        outcome: execution.outcome,
+                    });
+                }
+                catch {
+                    // Execution notifications are advisory and never affect monitoring.
+                }
+            }
+        }
+        this.seeded = true;
+    }
+}
+export function createTerminalNotificationWriter({ write = writeTerminal, tmux = Boolean(process.env.TMUX), } = {}) {
+    return {
+        notify(notification) {
+            const suffix = ` · ${sanitize(notification.issue)} · ${notification.outcome}`;
+            const projectBytes = Math.max(0, maximumPayloadBytes -
+                Buffer.byteLength(notificationPrefix + suffix, "utf8"));
+            const message = `${notificationPrefix}${truncateUtf8(sanitize(notification.project), projectBytes)}${suffix}`;
+            const osc = `\u001b]9;${message}\u001b\\`;
+            const sequence = tmux
+                ? `\u001bPtmux;${osc.replaceAll("\u001b", "\u001b\u001b")}\u001b\\`
+                : osc;
+            try {
+                const pending = write(sequence);
+                if (pending)
+                    void pending.catch(() => undefined);
+            }
+            catch {
+                // Execution notifications are advisory and never affect monitoring.
+            }
+        },
+    };
+}
+function isTerminal(outcome) {
+    return terminalOutcomeSet.has(outcome);
+}
+function sanitize(value) {
+    return [...value]
+        .filter((character) => {
+        const codePoint = character.codePointAt(0);
+        return !(codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f));
+    })
+        .join("")
+        .replace(whitespace, " ")
+        .trim();
+}
+function writeTerminal(value) {
+    return new Promise((resolve, reject) => {
+        writeFileDescriptor(process.stdout.fd, value, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+function truncateUtf8(value, maximumBytes) {
+    let result = "";
+    let bytes = 0;
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (bytes + characterBytes > maximumBytes)
+            break;
+        result += character;
+        bytes += characterBytes;
+    }
+    return result;
+}

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

@@ -1,12 +1,19 @@
 import type { RunRecord } from "../domain.js";
 import type { EventRecord, InvocationRecord } from "../store.js";
+type AvailableActions = {
+    stop: boolean;
+    retry: boolean;
+    recover: boolean;
+};
+export declare function wrapDetailLines(lines: string[], width: number): string[];
 export declare function summaryLines(run: RunRecord, now: number, event?: EventRecord): string[];
-export declare function detailLines(run: RunRecord, sessions: InvocationRecord[], now: number, recoveryReason?: string | undefined): string[];
-export declare function Lines({ lines, width, height, offset, }: {
+export declare function detailLines(run: RunRecord, sessions: InvocationRecord[], now: number, recoveryReason?: string | undefined, width?: number, available?: AvailableActions): string[];
+export declare function Lines({ lines, width, height, offset, outcome, }: {
     lines: string[];
     width: number;
     height: number;
     offset?: number;
+    outcome?: string;
 }): import("react").JSX.Element;
 export declare function RunList({ runs, selected, width, height, now, }: {
     runs: RunRecord[];
@@ -15,3 +22,4 @@ export declare function RunList({ runs, selected, width, height, now, }: {
     height: number;
     now: number;
 }): import("react").JSX.Element;
+export {};