@entelligentsia/forgecli 1.0.3 → 1.0.14

package/dist/extensions/forgecli/orchestrator-status-bar.js

@@ -0,0 +1,183 @@
+// orchestrator-status-bar.ts — One-line status bar for running orchestrations.
+//
+// Two render modes:
+//
+//   INACTIVE (default):
+//     [HELLO-S01-T01 ● plan ⠋] "preview…"  ↓ dashboard
+//
+//     Shows a compact summary with status, spinner, and a ↓ hint.
+//     Press ↓ to focus the status bar.
+//
+//   ACTIVE (user pressed ↓):
+//     ▸ [HELLO-S01-T01 ● plan ⠋] "preview…"  ⏎ open · esc back
+//
+//     Cursor glyph highlights the bar. Enter opens the dashboard overlay.
+//     Esc returns focus to the editor.
+//
+// The dashboard overlay (/forge:dashboard) remains the detailed view.
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+import { fmtTokenMeter } from "./viewport-renderer.js";
+// ── Braille spinner ────────────────────────────────────────────────────────
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 100;
+// ── Status glyph for a node ────────────────────────────────────────────────
+function nodeGlyph(status, theme) {
+    switch (status) {
+        case "completed":
+            return theme.fg("success", "✓");
+        case "running":
+            return theme.fg("accent", "●");
+        case "cancelling":
+            return theme.fg("warning", "⏳");
+        case "cancelled":
+            return theme.fg("muted", "⊘");
+        case "failed":
+            return theme.fg("error", "✗");
+        case "escalated":
+            return theme.fg("error", "▲");
+        case "pending":
+        default:
+            return theme.fg("dim", "○");
+    }
+}
+// ── OrchestratorStatusBar ──────────────────────────────────────────────────
+export class OrchestratorStatusBar {
+    tree;
+    theme;
+    active = false;
+    invalidationCb;
+    spinnerTimer;
+    spinnerIdx = 0;
+    onAction; // callback to open dashboard
+    disposeFns = [];
+    constructor(tree, theme) {
+        this.tree = tree;
+        this.theme = theme;
+        const onChange = () => this.invalidationCb?.();
+        this.tree.on("change", onChange);
+        this.tree.on("tree", onChange);
+        this.tree.on("tail", onChange);
+        this.tree.on("preview", onChange);
+        this.disposeFns.push(() => { this.tree.off("change", onChange); this.tree.off("tree", onChange); this.tree.off("tail", onChange); this.tree.off("preview", onChange); });
+    }
+    setInvalidationCallback(cb) {
+        this.invalidationCb = cb;
+        this.ensureSpinnerTimer();
+    }
+    setOnAction(cb) {
+        this.onAction = cb;
+    }
+    setActive(active) {
+        this.active = active;
+        this.invalidationCb?.();
+    }
+    isActive() {
+        return this.active;
+    }
+    ensureSpinnerTimer() {
+        if (this.spinnerTimer)
+            return;
+        this.spinnerTimer = setInterval(() => {
+            const anyActive = this.tree.getActiveRoots().some((r) => r.status === "running" || r.status === "cancelling");
+            if (!anyActive) {
+                // One last render to settle spinner, then stop.
+                this.invalidationCb?.();
+                if (this.spinnerTimer)
+                    clearInterval(this.spinnerTimer);
+                this.spinnerTimer = undefined;
+                return;
+            }
+            this.spinnerIdx = (this.spinnerIdx + 1) % SPINNER_FRAMES.length;
+            this.invalidationCb?.();
+        }, SPINNER_INTERVAL_MS);
+    }
+    render(width) {
+        const roots = this.tree.getActiveRoots();
+        if (roots.length === 0)
+            return []; // Hidden when nothing is running.
+        const dim = (s) => this.theme.fg("dim", s);
+        const accent = (s) => this.theme.fg("accent", s);
+        const bold = (s) => this.theme.bold(this.theme.fg("accent", s));
+        // Build a segment for each active root.
+        const segments = [];
+        for (const root of roots) {
+            // Find the deepest running leaf or the root itself.
+            const leaf = this.findDeepestRunningLeaf(root.id);
+            const displayNode = leaf ?? root;
+            const glyph = nodeGlyph(displayNode.status, this.theme);
+            // Label: root label, with current phase as suffix if different.
+            let label = root.label;
+            if (leaf && leaf.id !== root.id) {
+                const shortRole = leaf.id.includes(":") ? leaf.id.split(":").slice(1).join(":") : leaf.label;
+                label = `${root.label} · ${shortRole}`;
+            }
+            // Usage footer (right-aligned within segment).
+            const usage = this.tree.getSubtreeUsage(root.id);
+            const meter = fmtTokenMeter(usage);
+            const meterPart = meter ? dim(` ${meter}`) : "";
+            // Spinner for running nodes.
+            const spin = (displayNode.status === "running" || displayNode.status === "cancelling")
+                ? ` ${SPINNER_FRAMES[this.spinnerIdx]}`
+                : "";
+            // Turn preview (truncated).
+            const preview = displayNode.lastTurnPreview
+                ? dim(` "${truncateToWidth(displayNode.lastTurnPreview, 60)}"`)
+                : "";
+            const segment = `${glyph} ${bold(`[${label}]`)}${spin}${preview}${meterPart}`;
+            segments.push(segment);
+        }
+        // Right-side hint depends on active state.
+        const hint = this.active
+            ? dim(" ⏎ open · esc back")
+            : dim(" ↓ dashboard");
+        // Compose: join segments with separator, append hint.
+        const prefix = this.active ? accent("▸") + " " : "";
+        const joined = segments.join(dim(" │ "));
+        const line = `${prefix}${joined}${hint}`;
+        return [truncateToWidth(line, width)];
+    }
+    invalidate() {
+        // Re-render driven by external invalidationCb → tui.requestRender().
+    }
+    handleInput(data) {
+        if (!this.active)
+            return;
+        if (matchesKey(data, Key.enter)) {
+            this.active = false;
+            this.onAction?.(); // open dashboard
+        }
+        else if (matchesKey(data, Key.escape) || matchesKey(data, Key.up)) {
+            this.active = false; // deactivate, return to editor
+        }
+        this.invalidationCb?.();
+    }
+    dispose = () => {
+        if (this.spinnerTimer) {
+            clearInterval(this.spinnerTimer);
+            this.spinnerTimer = undefined;
+        }
+        for (const fn of this.disposeFns)
+            fn();
+        this.disposeFns = [];
+    };
+    /** Walk depth-first to find the deepest running/cancelling leaf. */
+    findDeepestRunningLeaf(id) {
+        const node = this.tree.getNode(id);
+        if (!node)
+            return undefined;
+        if (node.kind === "leaf" && (node.status === "running" || node.status === "cancelling")) {
+            return node;
+        }
+        for (const childId of node.children) {
+            const found = this.findDeepestRunningLeaf(childId);
+            if (found)
+                return found;
+        }
+        // If no running leaf, return the root if it's running.
+        if (node.status === "running" || node.status === "cancelling")
+            return node;
+        return undefined;
+    }
+}
+//# sourceMappingURL=orchestrator-status-bar.js.map

package/dist/extensions/forgecli/orchestrator-status-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-status-bar.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/orchestrator-status-bar.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/orchestrator-tree.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from "node:events";
+export type NodeKind = "orchestrator" | "leaf";
+export type NodeStatus = "pending" | "running" | "cancelling" | "cancelled" | "completed" | "failed" | "escalated";
+export interface UsageSnapshot {
+    input: number;
+    output: number;
+    cacheRead: number;
+}
+export interface NodeMetrics {
+    turn: number;
+    toolCount: number;
+    errCount: number;
+}
+export interface OrchestratorNode {
+    id: string;
+    label: string;
+    kind: NodeKind;
+    parentId: string | null;
+    children: string[];
+    status: NodeStatus;
+    startedAt: number;
+    endedAt?: number;
+    usage: UsageSnapshot;
+    model?: string;
+    provider?: string;
+    compression?: {
+        calls: number;
+        tokensSaved: number;
+    };
+    metrics: NodeMetrics;
+    iteration?: number;
+    tailBuffer: string[];
+    unreadWarnings: number;
+    firstTurnPreview?: string;
+    lastTurnPreview?: string;
+    promptPreview?: string;
+    outcomePreview?: string;
+    abortController?: AbortController;
+}
+export interface StartNodeOptions {
+    parentId?: string;
+    label?: string;
+    kind?: NodeKind;
+    promptPreview?: string;
+}
+export declare class OrchestratorTree extends EventEmitter {
+    private nodes;
+    private roots;
+    startNode(id: string, opts?: StartNodeOptions): OrchestratorNode;
+    completeNode(id: string, status: NodeStatus): void;
+    setNodeUsage(id: string, usage: UsageSnapshot): void;
+    setNodeModel(id: string, model: string, provider: string): void;
+    setNodeCompression(id: string, compression: {
+        calls: number;
+        tokensSaved: number;
+    }): void;
+    bumpNodeTurn(id: string): void;
+    incrementNodeToolCount(id: string, delta?: number): void;
+    incrementNodeErrCount(id: string, delta?: number): void;
+    setNodeIteration(id: string, iteration: number): void;
+    setNodeOutcome(id: string, preview: string): void;
+    appendTail(id: string, line: string, opts?: {
+        warning?: boolean;
+    }): void;
+    markTailRead(id: string): void;
+    setTurnPreview(id: string, preview: string): void;
+    requestCancel(id: string): boolean;
+    getAbortSignal(id: string): AbortSignal | undefined;
+    getNode(id: string): OrchestratorNode | undefined;
+    getChildren(id: string): OrchestratorNode[];
+    getAncestors(id: string): OrchestratorNode[];
+    getRoots(): OrchestratorNode[];
+    /** Active roots: all roots if any are running/cancelling, otherwise
+     *  only non-terminal roots. Prunes stale terminal roots that have no
+     *  running descendants — the dashboard should not show completed sprints
+     *  from prior invocations alongside the current one. */
+    getActiveRoots(): OrchestratorNode[];
+    /** Returns true if every node in the subtree rooted at `id` has reached a
+     *  terminal state (completed, failed, cancelled, or escalated). */
+    private isSubtreeTerminal;
+    /** Re-parent a node from its current position to a new parent (or to root
+     *  if newParentId is null). Removes from old parent's children and/or
+     *  roots, adds to new parent's children and/or roots, and updates the
+     *  node's parentId field. */
+    private reparentNode;
+    getSubtreeUsage(id: string): UsageSnapshot;
+    getSubtreeProgress(id: string): {
+        completed: number;
+        total: number;
+    };
+    /** Depth of a node (root = 0). Useful for tree indentation. */
+    getDepth(id: string): number;
+    private evictIfNeeded;
+    private removeSubtree;
+}
+export declare function getOrchestratorTree(): OrchestratorTree;

package/dist/extensions/forgecli/orchestrator-tree.js

@@ -0,0 +1,390 @@
+// orchestrator-tree.ts — Generic observable tree for orchestrator > subagent
+// visualization.
+//
+// Sibling to SessionRegistry (which drives the chip strip). The dashboard
+// overlay reads from OrchestratorTree; the chip strip reads from
+// SessionRegistry. Both are written to by the same orchestrator call-sites.
+//
+// The tree is depth-agnostic: Sprint>Tasks>Phases, Fix-bug>Phases, and
+// standalone Run-task are all fan-out trees with the same node shape. Any
+// future orchestrator (run-release, etc.) adds nodes without dashboard
+// changes.
+//
+// Node IDs are dot/colon-separated paths for readability:
+//   "FORGE-S27"                    — sprint root (orchestrator)
+//   "FORGE-S27-T01"                — task (orchestrator)
+//   "FORGE-S27-T01:plan:1"         — phase (leaf)
+//   "FORGE-S27:ceremony"           — ceremony (leaf)
+//
+// LRU-capped at MAX_NODES to bound memory across long-running processes.
+// Ring-buffer tail caps at MAX_TAIL_LINES_PER_NODE.
+import { EventEmitter } from "node:events";
+// ── Constants ──────────────────────────────────────────────────────────────
+const MAX_NODES = 50;
+const MAX_TAIL_LINES_PER_NODE = 2048;
+const MAX_TAIL_APPEND = 500; // per-append cap before trimming
+// ── OrchestratorTree ───────────────────────────────────────────────────────
+export class OrchestratorTree extends EventEmitter {
+    nodes = new Map();
+    roots = new Set();
+    // ── Mutation: lifecycle ────────────────────────────────────────────────
+    startNode(id, opts = {}) {
+        const existing = this.nodes.get(id);
+        if (existing) {
+            // Resume — refresh status and timestamps, keep events for visibility.
+            existing.status = "running";
+            existing.startedAt = Date.now();
+            existing.endedAt = undefined;
+            existing.abortController = new AbortController();
+            // Reconcile parentId: if the caller specifies a different parent,
+            // reparent the node so stale root placements self-correct.
+            const newParentId = opts.parentId ?? null;
+            const oldParentId = existing.parentId;
+            if (newParentId !== oldParentId) {
+                this.reparentNode(existing, oldParentId, newParentId);
+            }
+            // Re-apply label/kind if caller supplies them (resume may change role).
+            if (opts.label !== undefined)
+                existing.label = opts.label;
+            if (opts.kind !== undefined)
+                existing.kind = opts.kind;
+            if (opts.promptPreview !== undefined)
+                existing.promptPreview = opts.promptPreview;
+            this.emit("change", id);
+            this.emit("tree", id);
+            return existing;
+        }
+        const node = {
+            id,
+            label: opts.label ?? id,
+            kind: opts.kind ?? "leaf",
+            parentId: opts.parentId ?? null,
+            children: [],
+            status: "running",
+            startedAt: Date.now(),
+            usage: { input: 0, output: 0, cacheRead: 0 },
+            metrics: { turn: 0, toolCount: 0, errCount: 0 },
+            tailBuffer: [],
+            unreadWarnings: 0,
+            abortController: new AbortController(),
+        };
+        if (opts.promptPreview) {
+            node.promptPreview = opts.promptPreview;
+        }
+        // Link to parent.
+        if (node.parentId) {
+            const parent = this.nodes.get(node.parentId);
+            if (parent && !parent.children.includes(id)) {
+                parent.children.push(id);
+            }
+        }
+        else {
+            this.roots.add(id);
+        }
+        this.nodes.set(id, node);
+        this.evictIfNeeded();
+        this.emit("change", id);
+        this.emit("tree", id);
+        return node;
+    }
+    completeNode(id, status) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Idempotent for terminal states — don't clobber a success-path mark.
+        if (node.status !== "running" && node.status !== "cancelling")
+            return;
+        node.status = status;
+        node.endedAt = Date.now();
+        node.abortController = undefined;
+        this.emit("change", id);
+    }
+    // ── Mutation: telemetry ─────────────────────────────────────────────────
+    setNodeUsage(id, usage) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.usage = { input: usage.input, output: usage.output, cacheRead: usage.cacheRead };
+        this.emit("change", id);
+    }
+    setNodeModel(id, model, provider) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Only emit when the value actually changes — turn_end fires every
+        // turn and the model is stable across a phase.
+        if (node.provider === provider && node.model === model)
+            return;
+        node.model = model;
+        node.provider = provider;
+        this.emit("change", id);
+    }
+    setNodeCompression(id, compression) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.compression = { calls: compression.calls, tokensSaved: compression.tokensSaved };
+        this.emit("change", id);
+    }
+    bumpNodeTurn(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.turn++;
+        this.emit("change", id);
+    }
+    incrementNodeToolCount(id, delta = 1) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.toolCount += delta;
+        this.emit("change", id);
+    }
+    incrementNodeErrCount(id, delta = 1) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.metrics.errCount += delta;
+        this.emit("change", id);
+    }
+    setNodeIteration(id, iteration) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.iteration = iteration;
+        this.emit("change", id);
+    }
+    setNodeOutcome(id, preview) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.outcomePreview = preview;
+        this.emit("change", id);
+    }
+    // ── Mutation: tail buffer ───────────────────────────────────────────────
+    appendTail(id, line, opts) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        node.tailBuffer.push(line);
+        if (node.tailBuffer.length > MAX_TAIL_LINES_PER_NODE) {
+            node.tailBuffer.splice(0, node.tailBuffer.length - MAX_TAIL_LINES_PER_NODE);
+        }
+        if (opts?.warning)
+            node.unreadWarnings++;
+        this.emit("tail", id);
+    }
+    markTailRead(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        if (node.unreadWarnings === 0)
+            return;
+        node.unreadWarnings = 0;
+        this.emit("change", id);
+    }
+    setTurnPreview(id, preview) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        if (node.lastTurnPreview === preview)
+            return;
+        node.lastTurnPreview = preview;
+        if (node.firstTurnPreview === undefined)
+            node.firstTurnPreview = preview;
+        this.emit("preview", id);
+    }
+    // ── Mutation: cancellation ───────────────────────────────────────────────
+    requestCancel(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return false;
+        if (node.status !== "running")
+            return false;
+        node.status = "cancelling";
+        node.abortController?.abort();
+        this.emit("change", id);
+        return true;
+    }
+    getAbortSignal(id) {
+        return this.nodes.get(id)?.abortController?.signal;
+    }
+    // ── Queries ──────────────────────────────────────────────────────────────
+    getNode(id) {
+        return this.nodes.get(id);
+    }
+    getChildren(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return [];
+        return node.children
+            .map((cid) => this.nodes.get(cid))
+            .filter((n) => n !== undefined);
+    }
+    getAncestors(id) {
+        const result = [];
+        let current = this.nodes.get(id);
+        while (current?.parentId) {
+            const parent = this.nodes.get(current.parentId);
+            if (parent)
+                result.push(parent);
+            current = parent;
+        }
+        return result;
+    }
+    getRoots() {
+        return [...this.roots]
+            .map((id) => this.nodes.get(id))
+            .filter((n) => n !== undefined);
+    }
+    /** Active roots: all roots if any are running/cancelling, otherwise
+     *  only non-terminal roots. Prunes stale terminal roots that have no
+     *  running descendants — the dashboard should not show completed sprints
+     *  from prior invocations alongside the current one. */
+    getActiveRoots() {
+        const roots = this.getRoots();
+        const hasActive = roots.some((r) => r.status === "running" || r.status === "cancelling");
+        if (!hasActive)
+            return roots; // nothing in flight — show all
+        return roots.filter((r) => r.status === "running" ||
+            r.status === "cancelling" ||
+            r.status === "pending" ||
+            (r.kind === "orchestrator" && !this.isSubtreeTerminal(r.id)));
+    }
+    /** Returns true if every node in the subtree rooted at `id` has reached a
+     *  terminal state (completed, failed, cancelled, or escalated). */
+    isSubtreeTerminal(id) {
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            if (node.status !== "completed" &&
+                node.status !== "failed" &&
+                node.status !== "cancelled" &&
+                node.status !== "escalated") {
+                return false;
+            }
+            stack.push(...node.children);
+        }
+        return true;
+    }
+    /** Re-parent a node from its current position to a new parent (or to root
+     *  if newParentId is null). Removes from old parent's children and/or
+     *  roots, adds to new parent's children and/or roots, and updates the
+     *  node's parentId field. */
+    reparentNode(node, oldParentId, newParentId) {
+        if (oldParentId === newParentId)
+            return;
+        // Unlink from old parent (or roots).
+        if (oldParentId) {
+            const oldParent = this.nodes.get(oldParentId);
+            if (oldParent) {
+                oldParent.children = oldParent.children.filter((cid) => cid !== node.id);
+            }
+        }
+        else {
+            this.roots.delete(node.id);
+        }
+        // Link to new parent (or roots).
+        if (newParentId) {
+            const newParent = this.nodes.get(newParentId);
+            if (newParent && !newParent.children.includes(node.id)) {
+                newParent.children.push(node.id);
+            }
+        }
+        else {
+            this.roots.add(node.id);
+        }
+        node.parentId = newParentId;
+    }
+    getSubtreeUsage(id) {
+        const agg = { input: 0, output: 0, cacheRead: 0 };
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            agg.input += node.usage.input;
+            agg.output += node.usage.output;
+            agg.cacheRead += node.usage.cacheRead;
+            stack.push(...node.children);
+        }
+        return agg;
+    }
+    getSubtreeProgress(id) {
+        let completed = 0;
+        let total = 0;
+        const stack = [id];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const node = this.nodes.get(current);
+            if (!node)
+                continue;
+            if (node.kind === "leaf") {
+                total++;
+                if (node.status === "completed")
+                    completed++;
+            }
+            stack.push(...node.children);
+        }
+        return { completed, total };
+    }
+    /** Depth of a node (root = 0). Useful for tree indentation. */
+    getDepth(id) {
+        let depth = 0;
+        let current = this.nodes.get(id);
+        while (current?.parentId) {
+            depth++;
+            current = this.nodes.get(current.parentId);
+        }
+        return depth;
+    }
+    // ── Private ─────────────────────────────────────────────────────────────
+    evictIfNeeded() {
+        if (this.nodes.size <= MAX_NODES)
+            return;
+        // Evict the oldest completed/failed/cancelled root node.
+        const roots = this.getRoots();
+        const evictable = roots
+            .filter((r) => r.status === "completed" ||
+            r.status === "failed" ||
+            r.status === "cancelled" ||
+            r.status === "escalated")
+            .sort((a, b) => a.startedAt - b.startedAt);
+        if (evictable.length === 0)
+            return;
+        const victim = evictable[0];
+        this.removeSubtree(victim.id);
+    }
+    removeSubtree(id) {
+        const node = this.nodes.get(id);
+        if (!node)
+            return;
+        // Remove all descendants first.
+        for (const childId of [...node.children]) {
+            this.removeSubtree(childId);
+        }
+        // Unlink from parent.
+        if (node.parentId) {
+            const parent = this.nodes.get(node.parentId);
+            if (parent) {
+                parent.children = parent.children.filter((cid) => cid !== id);
+            }
+        }
+        else {
+            this.roots.delete(id);
+        }
+        this.nodes.delete(id);
+    }
+}
+// ── Singleton ──────────────────────────────────────────────────────────────
+let _tree;
+export function getOrchestratorTree() {
+    if (!_tree)
+        _tree = new OrchestratorTree();
+    return _tree;
+}
+//# sourceMappingURL=orchestrator-tree.js.map