agent-tempo 1.0.1

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

@@ -0,0 +1,56 @@
+/**
+ * Formatting utilities for the TUI.
+ * Timestamp formatting, text truncation, duration display,
+ * attachment-phase → label/color/icon mapping (post-#177).
+ */
+import type { MaestroPlayerInfo } from '../../types';
+/**
+ * The maestro session is the TUI's own dashboard attachment — a synthetic
+ * "player" the human operator drives directly, not a peer agent. It shows up
+ * in the maestro's player list (so `/players` is an honest representation of
+ * internal state), but headline counts in the status bar / context string
+ * should exclude it. Otherwise a fresh ensemble with one real player reads
+ * confusingly as "2 players (1 active, 1 pending)".
+ */
+export declare function isMaestroPlayer(p: {
+    playerId?: string;
+    playerType?: string;
+}): boolean;
+/** Filter the maestro out of a list of players for headline counts. */
+export declare function filterRealPlayers<T extends {
+    playerId?: string;
+    playerType?: string;
+}>(players: readonly T[]): T[];
+export type { MaestroPlayerInfo };
+/** Format an ISO timestamp as a short time string (HH:MM:SS). */
+export declare function formatTime(iso: string): string;
+/** Format an ISO timestamp as relative time (e.g., "2m ago"). */
+export declare function formatRelativeTime(iso: string): string;
+/** Truncate text to maxLen, appending ellipsis if truncated. */
+export declare function truncate(text: string, maxLen: number, ellipsis?: string): string;
+/** User-facing phase labels shown in the TUI. */
+export type PhaseLabel = 'active' | 'idle' | 'disconnected' | 'pending' | 'gone' | 'unknown';
+/** Icon-bucket name used to key into `statusIcons()` (src/tui/utils/platform.ts). */
+export type PhaseIconName = 'active' | 'stale' | 'pending' | 'blocked' | 'terminated';
+/** Collapse an attachment phase into its user-facing label. */
+export declare function phaseToLabel(phase?: string): PhaseLabel;
+/** Theme color (hex string or undefined under NO_COLOR) for a phase. */
+export declare function phaseToColor(phase?: string): string;
+/** Icon-bucket key for `statusIcons()` for a phase. */
+export declare function phaseToIconName(phase?: string): PhaseIconName;
+/**
+ * Word-wrap text to fit within maxWidth, breaking at word boundaries.
+ * Each original newline starts a new line. Returns at least one line.
+ */
+export declare function wordWrap(text: string, maxWidth: number): string[];
+/**
+ * Format the "↑ N earlier message(s)" indicator shown above a truncated
+ * message list. Returns null when no indicator should render.
+ *
+ * - count <= 0          → null (no indicator)
+ * - count === 1         → "↑ 1 earlier message" (singular)
+ * - count >= 2          → "↑ N earlier messages" (plural)
+ */
+export declare function formatEarlierIndicator(count: number): string | null;
+/** Format an event type for display. */
+export declare function formatEventType(type: string): string;

package/dist/tui/utils/format.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Formatting utilities for the TUI.
+ * Timestamp formatting, text truncation, duration display,
+ * attachment-phase → label/color/icon mapping (post-#177).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMaestroPlayer = isMaestroPlayer;
+exports.filterRealPlayers = filterRealPlayers;
+exports.formatTime = formatTime;
+exports.formatRelativeTime = formatRelativeTime;
+exports.truncate = truncate;
+exports.phaseToLabel = phaseToLabel;
+exports.phaseToColor = phaseToColor;
+exports.phaseToIconName = phaseToIconName;
+exports.wordWrap = wordWrap;
+exports.formatEarlierIndicator = formatEarlierIndicator;
+exports.formatEventType = formatEventType;
+const theme_1 = require("./theme");
+/**
+ * The maestro session is the TUI's own dashboard attachment — a synthetic
+ * "player" the human operator drives directly, not a peer agent. It shows up
+ * in the maestro's player list (so `/players` is an honest representation of
+ * internal state), but headline counts in the status bar / context string
+ * should exclude it. Otherwise a fresh ensemble with one real player reads
+ * confusingly as "2 players (1 active, 1 pending)".
+ */
+function isMaestroPlayer(p) {
+    return p.playerId === 'maestro' || p.playerType === 'maestro';
+}
+/** Filter the maestro out of a list of players for headline counts. */
+function filterRealPlayers(players) {
+    return players.filter((p) => !isMaestroPlayer(p));
+}
+/** Format an ISO timestamp as a short time string (HH:MM:SS). */
+function formatTime(iso) {
+    try {
+        const d = new Date(iso);
+        return d.toLocaleTimeString('en-US', { hour12: false });
+    }
+    catch {
+        return iso;
+    }
+}
+/** Format an ISO timestamp as relative time (e.g., "2m ago"). */
+function formatRelativeTime(iso) {
+    try {
+        const ms = Date.now() - new Date(iso).getTime();
+        if (ms < 0)
+            return 'just now';
+        if (ms < 60_000)
+            return `${Math.floor(ms / 1000)}s ago`;
+        if (ms < 3_600_000)
+            return `${Math.floor(ms / 60_000)}m ago`;
+        if (ms < 86_400_000)
+            return `${Math.floor(ms / 3_600_000)}h ago`;
+        return `${Math.floor(ms / 86_400_000)}d ago`;
+    }
+    catch {
+        return iso;
+    }
+}
+/** Truncate text to maxLen, appending ellipsis if truncated. */
+function truncate(text, maxLen, ellipsis = '...') {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - ellipsis.length) + ellipsis;
+}
+const PHASE_TO_LABEL = Object.freeze({
+    attached: 'active',
+    processing: 'active',
+    awaiting: 'idle',
+    draining: 'disconnected',
+    detached: 'disconnected',
+    booting: 'pending',
+    gone: 'gone',
+});
+const LABEL_TO_COLOR = Object.freeze({
+    active: theme_1.THEME.success,
+    idle: theme_1.THEME.text,
+    disconnected: theme_1.THEME.warning,
+    pending: theme_1.THEME.dim,
+    gone: theme_1.THEME.dim,
+    unknown: theme_1.THEME.text,
+});
+const LABEL_TO_ICON_NAME = Object.freeze({
+    active: 'active', // ● (filled)
+    idle: 'stale', // ○ (hollow, neutral)
+    disconnected: 'blocked', // ◐ (half, yellow)
+    pending: 'pending', // ◔ (quarter, dim)
+    gone: 'terminated', // ✕
+    unknown: 'blocked', // ? → cautionary
+});
+/** Collapse an attachment phase into its user-facing label. */
+function phaseToLabel(phase) {
+    if (!phase)
+        return 'unknown';
+    return PHASE_TO_LABEL[phase] ?? 'unknown';
+}
+/** Theme color (hex string or undefined under NO_COLOR) for a phase. */
+function phaseToColor(phase) {
+    return LABEL_TO_COLOR[phaseToLabel(phase)];
+}
+/** Icon-bucket key for `statusIcons()` for a phase. */
+function phaseToIconName(phase) {
+    return LABEL_TO_ICON_NAME[phaseToLabel(phase)];
+}
+/**
+ * Word-wrap text to fit within maxWidth, breaking at word boundaries.
+ * Each original newline starts a new line. Returns at least one line.
+ */
+function wordWrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const result = [];
+    for (const raw of text.split('\n')) {
+        const words = raw.split(' ');
+        let current = '';
+        for (const word of words) {
+            if (current && current.length + 1 + word.length > maxWidth) {
+                result.push(current);
+                current = word;
+            }
+            else {
+                current = current ? current + ' ' + word : word;
+            }
+        }
+        result.push(current);
+    }
+    return result.length > 0 ? result : [''];
+}
+/**
+ * Format the "↑ N earlier message(s)" indicator shown above a truncated
+ * message list. Returns null when no indicator should render.
+ *
+ * - count <= 0          → null (no indicator)
+ * - count === 1         → "↑ 1 earlier message" (singular)
+ * - count >= 2          → "↑ N earlier messages" (plural)
+ */
+function formatEarlierIndicator(count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return null;
+    const label = count === 1 ? 'earlier message' : 'earlier messages';
+    return `\u2191 ${count} ${label}`;
+}
+/** Format an event type for display. */
+function formatEventType(type) {
+    switch (type) {
+        case 'player_joined': return 'joined';
+        case 'player_left': return 'left';
+        case 'status_changed': return 'status';
+        case 'part_changed': return 'part';
+        default: return type;
+    }
+}

package/dist/tui/utils/fullscreen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fullscreen utilities for the TUI.
+ *
+ * Clears the screen and hides the cursor on entry, shows cursor on exit.
+ * Stays on the primary screen buffer so <Static> items become native
+ * terminal scrollback that persists after exit.
+ */
+/** Whether fullscreen mode is supported and enabled. */
+export declare function fullscreenSupported(): boolean;
+/**
+ * Enter fullscreen mode — clears the screen and hides the cursor.
+ * Stays on the primary buffer so Static items persist as scrollback.
+ * No-op if fullscreen is not supported.
+ * @returns true if fullscreen was entered, false if skipped.
+ */
+export declare function enterFullscreen(): boolean;
+/**
+ * Exit fullscreen mode — shows the cursor.
+ * No buffer restore needed since we stay on the primary buffer.
+ * Safe to call even if fullscreen was never entered.
+ */
+export declare function exitFullscreen(): void;
+export declare function registerFullscreenCleanup(): void;

package/dist/tui/utils/fullscreen.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Fullscreen utilities for the TUI.
+ *
+ * Clears the screen and hides the cursor on entry, shows cursor on exit.
+ * Stays on the primary screen buffer so <Static> items become native
+ * terminal scrollback that persists after exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fullscreenSupported = fullscreenSupported;
+exports.enterFullscreen = enterFullscreen;
+exports.exitFullscreen = exitFullscreen;
+exports.registerFullscreenCleanup = registerFullscreenCleanup;
+/** Whether fullscreen mode is supported and enabled. */
+function fullscreenSupported() {
+    // User opt-out
+    if (process.env.AGENT_TEMPO_NO_FULLSCREEN === '1')
+        return false;
+    // Legacy cmd.exe on Windows doesn't support alternate buffer.
+    // Windows Terminal sets WT_SESSION; if absent on win32, skip.
+    if (process.platform === 'win32' && !process.env.WT_SESSION)
+        return false;
+    // Need a writable stdout
+    if (!process.stdout.isTTY)
+        return false;
+    return true;
+}
+/**
+ * Enter fullscreen mode — clears the screen and hides the cursor.
+ * Stays on the primary buffer so Static items persist as scrollback.
+ * No-op if fullscreen is not supported.
+ * @returns true if fullscreen was entered, false if skipped.
+ */
+function enterFullscreen() {
+    if (!fullscreenSupported())
+        return false;
+    // Clear screen + cursor home + hide cursor (no alternate buffer)
+    process.stdout.write('\x1b[2J\x1b[H\x1b[?25l');
+    return true;
+}
+/**
+ * Exit fullscreen mode — shows the cursor.
+ * No buffer restore needed since we stay on the primary buffer.
+ * Safe to call even if fullscreen was never entered.
+ */
+function exitFullscreen() {
+    // Show cursor (no buffer restore — primary buffer preserved)
+    process.stdout.write('\x1b[?25h');
+}
+/**
+ * Register cleanup handlers to exit fullscreen on process termination.
+ * Call once after enterFullscreen(). Idempotent — guards against double-registration.
+ */
+let cleanupRegistered = false;
+function registerFullscreenCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    const cleanup = () => {
+        exitFullscreen();
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        cleanup();
+        process.exit(0);
+    });
+}

package/dist/tui/utils/history.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Load command history from disk.
+ * Returns empty array if file doesn't exist or is corrupted.
+ */
+export declare function loadHistory(): string[];
+/**
+ * Save command history to disk.
+ * Creates ~/.agent-tempo/ if it doesn't exist.
+ */
+export declare function saveHistory(entries: string[]): void;

package/dist/tui/utils/history.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadHistory = loadHistory;
+exports.saveHistory = saveHistory;
+/**
+ * Persistent command history for the TUI.
+ * Saves to ~/.agent-tempo/tui-history.json.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const HISTORY_DIR = path.join(os.homedir(), '.agent-tempo');
+const HISTORY_FILE = path.join(HISTORY_DIR, 'tui-history.json');
+const MAX_ENTRIES = 500;
+const CURRENT_VERSION = 1;
+/**
+ * Load command history from disk.
+ * Returns empty array if file doesn't exist or is corrupted.
+ */
+function loadHistory() {
+    try {
+        if (!fs.existsSync(HISTORY_FILE))
+            return [];
+        const raw = fs.readFileSync(HISTORY_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        if (data.version !== CURRENT_VERSION || !Array.isArray(data.entries))
+            return [];
+        return data.entries.slice(-MAX_ENTRIES);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Save command history to disk.
+ * Creates ~/.agent-tempo/ if it doesn't exist.
+ */
+function saveHistory(entries) {
+    try {
+        if (!fs.existsSync(HISTORY_DIR)) {
+            fs.mkdirSync(HISTORY_DIR, { recursive: true });
+        }
+        const data = {
+            version: CURRENT_VERSION,
+            entries: entries.slice(-MAX_ENTRIES),
+        };
+        fs.writeFileSync(HISTORY_FILE, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch {
+        // Silently fail — history is non-critical
+    }
+}

package/dist/tui/utils/platform.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Platform detection utilities for the TUI.
+ * Determines Unicode support, SSH sessions, and terminal capabilities.
+ */
+/** Whether the terminal supports Unicode box-drawing and status icons. */
+export declare function supportsUnicode(): boolean;
+/** Whether we're running inside an SSH session. */
+export declare function isSSH(): boolean;
+/** Get terminal dimensions, with minimum fallback. */
+export declare function getTerminalSize(): {
+    columns: number;
+    rows: number;
+};
+/** Minimum terminal size for the TUI. */
+export declare const MIN_COLUMNS = 80;
+export declare const MIN_ROWS = 24;
+/** Check if terminal meets minimum size requirements. */
+export declare function isTerminalLargeEnough(): boolean;
+/** Status icons — Unicode by default, ASCII fallback. */
+export declare function statusIcons(unicode?: boolean): {
+    active: string;
+    stale: string;
+    pending: string;
+    blocked: string;
+    terminated: string;
+    conductor: string;
+    player: string;
+    arrow: string;
+    check: string;
+    cross: string;
+    ellipsis: string;
+};
+/** A colored text segment for braille rendering. */
+export interface BrailleSegment {
+    char: string;
+    color: string;
+}
+/** A row of braille segments (may have mixed colors). */
+export type BrailleLine = BrailleSegment[];
+/**
+ * Braille metronome — 3 frames (left, center, right).
+ * Renders at 60×48 dot resolution (30 cols × 12 rows of braille characters).
+ * Thin hairline triangle outline with thin pendulum arm and small pivot dot.
+ */
+export declare function metronomeBrailleFrames(): BrailleLine[][];