@ai-agent-forge/agent-forge 0.86.3 → 0.86.5

package/dist/modes/interactive/components/workflow-view.js

@@ -0,0 +1,638 @@
+/**
+ * Workflow overlay view (§9 L2/L3 of docs/design/工作流编排插件设计.md).
+ *
+ * Read-only panorama (L2) and transition stream (L3) rendered from the
+ * session's `workflow.state` / `workflow.transition` custom entries — the
+ * same isomorphic read the footer performs on `goal.state`, so the plugin
+ * does not need to be present and this module never imports plugin code.
+ * Waiting-condition labels mirror the engine's `computeWaitingOn` order
+ * (active-limit precedes write-scope conflict); plan lookups read the latest
+ * `plan.state` snapshot the same way.
+ *
+ * Operations are never executed here: approve/reject/skip/cancel forward an
+ * action text (e.g. `approve stage s2-review`) to the conversation input and
+ * the main agent drives it through workflow_advance — rendering and execution
+ * stay separated (设计 §9 L2 "转发到对话").
+ */
+import { Container, getKeybindings, Text, truncateToWidth } from "@agent-forge/tui";
+import { theme } from "../theme/theme.js";
+import { DynamicBorder } from "./dynamic-border.js";
+import { keyHint, rawKeyHint } from "./keybinding-hints.js";
+const STAGE_STATUSES = ["pending", "active", "awaiting_review", "completed", "failed", "skipped"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function parseStageSpec(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = stringOrUndefined(value.id);
+    if (id === undefined)
+        return undefined;
+    const dependsOn = Array.isArray(value.dependsOn) ? value.dependsOn.filter(isString) : [];
+    const acceptance = isRecord(value.objective) && Array.isArray(value.objective.acceptance) ? value.objective.acceptance : [];
+    const scope = Array.isArray(value.scope) ? value.scope.filter(isString) : undefined;
+    return {
+        id,
+        title: stringOrUndefined(value.title) ?? id,
+        dependsOn,
+        planId: stringOrUndefined(value.planId),
+        kind: value.kind === "read" ? "read" : "write",
+        scope: scope !== undefined && scope.length > 0 ? scope : undefined,
+        acceptanceIds: acceptance
+            .map((item) => (isRecord(item) ? stringOrUndefined(item.id) : undefined))
+            .filter((item) => item !== undefined),
+    };
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function parseStageRuntime(value) {
+    if (!isRecord(value))
+        return undefined;
+    const stageId = stringOrUndefined(value.stageId);
+    const status = stringOrUndefined(value.status);
+    if (stageId === undefined || status === undefined || !STAGE_STATUSES.includes(status))
+        return undefined;
+    const evidence = Array.isArray(value.evidence) ? value.evidence : [];
+    const covered = new Set();
+    let evidenceCount = 0;
+    for (const item of evidence) {
+        if (!isRecord(item))
+            continue;
+        evidenceCount++;
+        const acceptanceId = stringOrUndefined(item.acceptanceId);
+        if (acceptanceId !== undefined)
+            covered.add(acceptanceId);
+    }
+    return {
+        stageId,
+        status: status,
+        attempts: typeof value.attempts === "number" ? value.attempts : 0,
+        evidenceCount,
+        coveredAcceptanceIds: covered,
+    };
+}
+function parseWorkflowRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = stringOrUndefined(value.id);
+    const title = stringOrUndefined(value.title);
+    const status = stringOrUndefined(value.status);
+    if (id === undefined || title === undefined || status === undefined)
+        return undefined;
+    const stages = [];
+    for (const item of Array.isArray(value.stages) ? value.stages : []) {
+        const spec = parseStageSpec(item);
+        if (spec !== undefined)
+            stages.push(spec);
+    }
+    const runtime = new Map();
+    for (const item of Array.isArray(value.runtime) ? value.runtime : []) {
+        const parsed = parseStageRuntime(item);
+        if (parsed !== undefined)
+            runtime.set(parsed.stageId, parsed);
+    }
+    const diagnostics = Array.isArray(value.diagnostics) ? value.diagnostics.filter(isString) : [];
+    return {
+        id,
+        title,
+        status,
+        revision: typeof value.revision === "number" ? value.revision : 0,
+        goalId: stringOrUndefined(value.goalId),
+        maxActiveStages: typeof value.maxActiveStages === "number" ? value.maxActiveStages : 4,
+        maxRetreats: typeof value.maxRetreats === "number" ? value.maxRetreats : 3,
+        retreatCount: typeof value.retreatCount === "number" ? value.retreatCount : 0,
+        diagnostics,
+        stages,
+        runtime,
+    };
+}
+/** Latest `plan.state` snapshot reduced to id -> status (plan-dangling / plan-incomplete labels). */
+function parsePlanStatuses(data) {
+    const statuses = new Map();
+    if (!isRecord(data) || !Array.isArray(data.plans))
+        return statuses;
+    for (const item of data.plans) {
+        if (!isRecord(item))
+            continue;
+        const id = stringOrUndefined(item.id);
+        const status = stringOrUndefined(item.status);
+        if (id !== undefined && status !== undefined)
+            statuses.set(id, status);
+    }
+    return statuses;
+}
+function parseTransition(value) {
+    if (!isRecord(value))
+        return undefined;
+    const workflowId = stringOrUndefined(value.workflowId);
+    const from = stringOrUndefined(value.from);
+    const to = stringOrUndefined(value.to);
+    const reason = isRecord(value.reason) ? value.reason : undefined;
+    const code = reason !== undefined ? stringOrUndefined(reason.code) : undefined;
+    if (workflowId === undefined ||
+        from === undefined ||
+        to === undefined ||
+        code === undefined ||
+        typeof value.revision !== "number") {
+        return undefined;
+    }
+    return {
+        revision: value.revision,
+        workflowId,
+        stageId: stringOrUndefined(value.stageId),
+        from,
+        to,
+        trigger: stringOrUndefined(value.trigger) ?? "tool",
+        code,
+        message: reason !== undefined ? (stringOrUndefined(reason.message) ?? "") : "",
+        detail: reason !== undefined ? stringOrUndefined(reason.detail) : undefined,
+    };
+}
+function scopesIntersect(a, b) {
+    if (a === undefined || a.length === 0 || b === undefined || b.length === 0)
+        return true;
+    return a.some((tag) => b.includes(tag));
+}
+function findScopeConflict(workflow, spec) {
+    if (spec.kind !== "write")
+        return null;
+    for (const other of workflow.stages) {
+        if (other.id === spec.id || other.kind !== "write")
+            continue;
+        if (workflow.runtime.get(other.id)?.status !== "active")
+            continue;
+        if (scopesIntersect(spec.scope, other.scope))
+            return other.id;
+    }
+    return null;
+}
+function uncoveredAcceptanceIds(spec, runtime) {
+    if (runtime === undefined)
+        return [...spec.acceptanceIds];
+    return spec.acceptanceIds.filter((id) => !runtime.coveredAcceptanceIds.has(id));
+}
+/**
+ * §8.1 waiting-condition label, mirroring the engine's `computeWaitingOn`
+ * check order (active-limit precedes write-scope conflict) so the overlay
+ * names the same condition the audit stream recorded. Plan lookups use the
+ * latest `plan.state` snapshot instead of the engine's live dependency.
+ */
+function computeWaitingOn(workflow, spec, runtime, planStatuses) {
+    const status = runtime?.status ?? "pending";
+    if (status === "awaiting_review")
+        return "review";
+    if (status === "pending") {
+        if (workflow.status === "draft")
+            return "not-yet-active";
+        if ((runtime?.attempts ?? 0) > 0) {
+            if (spec.acceptanceIds.length === 0)
+                return "retry-wait";
+            return `acceptance-missing:[${uncoveredAcceptanceIds(spec, runtime).join(", ")}]`;
+        }
+        const incomplete = spec.dependsOn.filter((dep) => {
+            const dependency = workflow.runtime.get(dep)?.status;
+            return dependency !== "completed" && dependency !== "skipped";
+        });
+        if (incomplete.length > 0)
+            return `deps-incomplete:[${incomplete.join(", ")}]`;
+        if (spec.planId !== undefined && !planStatuses.has(spec.planId))
+            return "plan-dangling";
+        const activeCount = [...workflow.runtime.values()].filter((item) => item.status === "active").length;
+        if (activeCount >= workflow.maxActiveStages)
+            return "active-limit";
+        const conflict = findScopeConflict(workflow, spec);
+        if (conflict !== null)
+            return `write-scope-conflict:[${conflict}]`;
+        return "not-yet-active";
+    }
+    if (status === "active") {
+        if (spec.planId === undefined)
+            return null;
+        const planStatus = planStatuses.get(spec.planId);
+        if (planStatus === undefined)
+            return "plan-dangling";
+        if (planStatus !== "completed")
+            return "plan-incomplete";
+        return null;
+    }
+    return null;
+}
+function buildStageRows(workflow, planStatuses) {
+    const rows = [];
+    const visited = new Set();
+    const walk = (spec, depth) => {
+        if (visited.has(spec.id)) {
+            rows.push({
+                workflowId: workflow.id,
+                stageId: spec.id,
+                title: spec.title,
+                depth,
+                status: workflow.runtime.get(spec.id)?.status ?? "pending",
+                waitingOn: null,
+                attempts: 0,
+                evidenceCount: 0,
+                scopeConflict: null,
+                backReference: true,
+            });
+            return;
+        }
+        visited.add(spec.id);
+        const runtime = workflow.runtime.get(spec.id);
+        rows.push({
+            workflowId: workflow.id,
+            stageId: spec.id,
+            title: spec.title,
+            depth,
+            status: runtime?.status ?? "pending",
+            waitingOn: computeWaitingOn(workflow, spec, runtime, planStatuses),
+            attempts: runtime?.attempts ?? 0,
+            evidenceCount: runtime?.evidenceCount ?? 0,
+            scopeConflict: findScopeConflict(workflow, spec),
+            backReference: false,
+        });
+        for (const child of workflow.stages.filter((item) => item.dependsOn.includes(spec.id))) {
+            walk(child, depth + 1);
+        }
+    };
+    for (const root of workflow.stages.filter((item) => item.dependsOn.length === 0)) {
+        walk(root, 0);
+    }
+    // Stages unreachable from a root (defensive; the engine validates acyclic
+    // graphs) still render at the top level, mirroring the L1 text panorama.
+    for (const spec of workflow.stages) {
+        if (!visited.has(spec.id))
+            walk(spec, 0);
+    }
+    return rows;
+}
+/**
+ * Build the L2/L3 view model from session entries: the latest
+ * `workflow.state` snapshot plus the `workflow.transition` audit stream
+ * (newest first, capped). Malformed records are skipped, never thrown.
+ */
+export function buildWorkflowViewModel(entries, transitionLimit = 30) {
+    let stateData;
+    let hasStateEntry = false;
+    let planData;
+    const transitions = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom")
+            continue;
+        if (entry.customType === "workflow.state") {
+            hasStateEntry = true;
+            stateData = entry.data;
+        }
+        else if (entry.customType === "plan.state") {
+            planData = entry.data;
+        }
+        else if (entry.customType === "workflow.transition") {
+            const parsed = parseTransition(entry.data);
+            if (parsed !== undefined)
+                transitions.push(parsed);
+        }
+    }
+    const planStatuses = parsePlanStatuses(planData);
+    let blocks;
+    if (hasStateEntry) {
+        const workflows = isRecord(stateData) && Array.isArray(stateData.workflows) ? stateData.workflows : [];
+        blocks = workflows
+            .map((item) => {
+            const parsed = parseWorkflowRecord(item);
+            if (parsed === undefined)
+                return undefined;
+            return {
+                workflowId: parsed.id,
+                title: parsed.title,
+                status: parsed.status,
+                revision: parsed.revision,
+                goalId: parsed.goalId,
+                activeCount: [...parsed.runtime.values()].filter((item) => item.status === "active").length,
+                maxActiveStages: parsed.maxActiveStages,
+                retreatCount: parsed.retreatCount,
+                maxRetreats: parsed.maxRetreats,
+                diagnostics: [...parsed.diagnostics],
+                stages: buildStageRows(parsed, planStatuses),
+            };
+        })
+            .filter((block) => block !== undefined);
+    }
+    const activeRecord = blocks?.filter((block) => block.status === "draft" || block.status === "running").at(-1);
+    const activeWorkflowId = activeRecord?.workflowId ?? blocks?.at(-1)?.workflowId;
+    return {
+        panorama: blocks,
+        transitions: transitions.slice(-transitionLimit).reverse(),
+        activeWorkflowId,
+    };
+}
+/** Action text injected into the conversation input, e.g. `approve stage s2-review`. */
+export function buildWorkflowActionText(action, workflowId, stageId) {
+    if (action === "cancel" || stageId === undefined)
+        return `cancel workflow ${workflowId}`;
+    return `${action} stage ${stageId}`;
+}
+function stageStatusColor(status) {
+    switch (status) {
+        case "active":
+            return (text) => theme.fg("accent", text);
+        case "awaiting_review":
+            return (text) => theme.fg("warning", text);
+        case "completed":
+            return (text) => theme.fg("success", text);
+        case "failed":
+            return (text) => theme.fg("error", text);
+        case "skipped":
+            return (text) => theme.fg("dim", text);
+        case "pending":
+            return (text) => theme.fg("muted", text);
+    }
+}
+function workflowStatusColor(status) {
+    if (status === "running")
+        return (text) => theme.fg("accent", text);
+    if (status === "completed")
+        return (text) => theme.fg("success", text);
+    if (status === "failed")
+        return (text) => theme.fg("error", text);
+    return (text) => theme.fg("dim", text);
+}
+function transitionCodeColor(code) {
+    if (code.includes("failed") || code.includes("retreat") || code.includes("error") || code.includes("limit")) {
+        return (text) => theme.fg("error", text);
+    }
+    if (code.includes("held") || code.includes("retry") || code.includes("amended")) {
+        return (text) => theme.fg("warning", text);
+    }
+    return (text) => theme.fg("muted", text);
+}
+/** Renders the visible row window; reads live state from the owning component. */
+class WorkflowRowsView {
+    view;
+    constructor(view) {
+        this.view = view;
+    }
+    invalidate() { }
+    render(width) {
+        return this.view.renderRows(width);
+    }
+}
+export class WorkflowViewComponent extends Container {
+    onClose;
+    onForwardAction;
+    config;
+    mode = "panorama";
+    rows = [];
+    selectedIndex = 0;
+    offset = 0;
+    titleText;
+    modeHintText;
+    helpText;
+    flashText;
+    cache;
+    flashTimeout = null;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.titleText = new Text(theme.fg("accent", theme.bold("  Workflow Overview")), 1, 0);
+        this.modeHintText = new Text("", 1, 0);
+        this.helpText = new Text("", 1, 0);
+        this.flashText = new Text("", 1, 0);
+        this.updateModeTexts();
+        this.addChild(new DynamicBorder());
+        this.addChild(this.titleText);
+        this.addChild(this.modeHintText);
+        this.addChild(new WorkflowRowsView(this));
+        this.addChild(this.flashText);
+        this.addChild(this.helpText);
+        this.addChild(new DynamicBorder());
+    }
+    dispose() {
+        if (this.flashTimeout !== null) {
+            clearTimeout(this.flashTimeout);
+            this.flashTimeout = null;
+        }
+    }
+    updateModeTexts() {
+        const label = this.mode === "panorama" ? "panorama" : "transition log (newest first)";
+        this.modeHintText.setText(theme.fg("dim", `  ${label}`));
+        this.helpText.setText(this.buildHelpLine());
+    }
+    buildHelpLine() {
+        const parts = [rawKeyHint("↑↓", "move")];
+        if (this.mode === "panorama") {
+            parts.push(rawKeyHint("tab/l", "log"), rawKeyHint("a", "approve"), rawKeyHint("r", "reject"), rawKeyHint("s", "skip"), rawKeyHint("c", "cancel"));
+        }
+        else {
+            parts.push(rawKeyHint("tab/l", "panorama"));
+        }
+        parts.push(keyHint("tui.select.cancel", "close"));
+        return `  ${parts.join("  ")}`;
+    }
+    getModel() {
+        const entries = this.config.getEntries();
+        if (this.cache && this.cache.entries === entries && this.cache.length === entries.length) {
+            return this.cache.model;
+        }
+        const model = buildWorkflowViewModel(entries);
+        this.cache = { entries, length: entries.length, model };
+        return model;
+    }
+    buildRows(model) {
+        const rows = [];
+        if (this.mode === "log") {
+            if (model.transitions.length === 0) {
+                rows.push({ text: "  no workflow transitions recorded", stage: undefined });
+                return rows;
+            }
+            for (const transition of model.transitions) {
+                const stage = transition.stageId !== undefined ? `/${transition.stageId}` : "";
+                const detail = transition.detail !== undefined ? ` — ${transition.detail}` : "";
+                const code = transitionCodeColor(transition.code)(transition.code);
+                rows.push({
+                    text: `  #${transition.revision} ${transition.workflowId}${stage} ${transition.from} -> ${transition.to} [${transition.trigger}] ${code}: ${transition.message}${detail}`,
+                    stage: undefined,
+                });
+            }
+            return rows;
+        }
+        const blocks = model.panorama;
+        if (blocks === undefined) {
+            rows.push({ text: "  no workflow.state entry in this session", stage: undefined });
+            return rows;
+        }
+        if (blocks.length === 0) {
+            rows.push({ text: "  no workflows in this session; create one with workflow_set", stage: undefined });
+            return rows;
+        }
+        for (const block of blocks) {
+            const status = workflowStatusColor(block.status)(block.status);
+            rows.push({
+                text: `  workflow "${block.title}" (${block.workflowId}) — ${status} · revision ${block.revision} · active ${block.activeCount}/${block.maxActiveStages} · retreats ${block.retreatCount}/${block.maxRetreats}`,
+                stage: undefined,
+            });
+            if (block.goalId !== undefined) {
+                rows.push({ text: `    goal: ${block.goalId}`, stage: undefined });
+            }
+            for (const stage of block.stages) {
+                rows.push({
+                    text: this.formatStageRow(stage),
+                    stage: { workflowId: block.workflowId, stageId: stage.stageId },
+                });
+            }
+            if (block.diagnostics.length > 0) {
+                rows.push({ text: "    diagnostics:", stage: undefined });
+                for (const diagnostic of block.diagnostics) {
+                    rows.push({ text: theme.fg("warning", `      - ${diagnostic}`), stage: undefined });
+                }
+            }
+            rows.push({ text: "", stage: undefined });
+        }
+        return rows;
+    }
+    formatStageRow(stage) {
+        const pad = "  ".repeat(stage.depth + 1);
+        if (stage.backReference) {
+            return `${pad}  -> ${stage.stageId} (shown above)`;
+        }
+        const bits = [`- ${stage.stageId} [${stageStatusColor(stage.status)(stage.status)}] ${stage.title}`];
+        if (stage.waitingOn !== null)
+            bits.push(theme.fg("dim", `— waiting: ${stage.waitingOn}`));
+        if (stage.attempts > 0)
+            bits.push(theme.fg("dim", `· attempts ${stage.attempts}`));
+        if (stage.evidenceCount > 0)
+            bits.push(theme.fg("dim", `· evidence ${stage.evidenceCount}`));
+        if (stage.scopeConflict !== null) {
+            bits.push(theme.fg("warning", `⚠ scope:${stage.scopeConflict}`));
+        }
+        return `${pad}${bits.join(" ")}`;
+    }
+    /** Rows are rebuilt lazily on access; the key couples rebuild + selection restore. */
+    syncRows() {
+        const model = this.getModel();
+        const previous = this.rows[this.selectedIndex]?.stage;
+        this.rows = this.buildRows(model);
+        if (previous !== undefined) {
+            const restored = this.rows.findIndex((row) => row.stage?.stageId === previous.stageId);
+            if (restored !== -1)
+                this.selectedIndex = restored;
+        }
+        if (this.selectedIndex >= this.rows.length)
+            this.selectedIndex = Math.max(0, this.rows.length - 1);
+        this.clampOffset();
+    }
+    clampOffset() {
+        const maxRows = Math.max(1, this.config.maxRows);
+        if (this.selectedIndex < this.offset)
+            this.offset = this.selectedIndex;
+        if (this.selectedIndex >= this.offset + maxRows)
+            this.offset = this.selectedIndex - maxRows + 1;
+        if (this.offset < 0)
+            this.offset = 0;
+    }
+    renderRows(width) {
+        this.syncRows();
+        const maxRows = Math.max(1, this.config.maxRows);
+        const lines = [];
+        for (let index = this.offset; index < Math.min(this.rows.length, this.offset + maxRows); index++) {
+            const row = this.rows[index];
+            if (row === undefined)
+                continue;
+            const selected = index === this.selectedIndex;
+            const prefix = selected ? theme.fg("accent", "→ ") : "  ";
+            lines.push(truncateToWidth(`${prefix}${row.text}`, width));
+        }
+        const hiddenAbove = this.offset;
+        const hiddenBelow = this.rows.length - this.offset - maxRows;
+        const hidden = [];
+        if (hiddenAbove > 0)
+            hidden.push(`↑${hiddenAbove}`);
+        if (hiddenBelow > 0)
+            hidden.push(`↓${hiddenBelow}`);
+        // Fixed output height (exactly maxRows content rows plus this final
+        // indicator row), the same contract as agents-view renderRows: the
+        // overlay's grid footprint must not change with mode switches or row
+        // counts, or the chat/editor layout boundary moves between frames.
+        while (lines.length < maxRows)
+            lines.push(truncateToWidth(" ", width));
+        lines.push(truncateToWidth(hidden.length > 0 ? theme.fg("dim", `  ${hidden.join(" ")}`) : " ", width));
+        return lines;
+    }
+    move(delta) {
+        if (this.rows.length === 0)
+            return;
+        this.selectedIndex = Math.min(this.rows.length - 1, Math.max(0, this.selectedIndex + delta));
+        this.clampOffset();
+    }
+    flash(message) {
+        this.flashText.setText(theme.fg("warning", `  ${message}`));
+        if (this.flashTimeout !== null)
+            clearTimeout(this.flashTimeout);
+        this.flashTimeout = setTimeout(() => {
+            this.flashText.setText("");
+            this.flashTimeout = null;
+            this.config.requestRender?.();
+        }, 2500);
+        this.config.requestRender?.();
+    }
+    toggleMode() {
+        this.mode = this.mode === "panorama" ? "log" : "panorama";
+        this.selectedIndex = 0;
+        this.offset = 0;
+        this.updateModeTexts();
+        this.config.requestRender?.();
+    }
+    forward(action) {
+        const selected = this.rows[this.selectedIndex];
+        if (selected?.stage === undefined) {
+            if (action === "cancel") {
+                const workflowId = this.getModel().activeWorkflowId;
+                if (workflowId === undefined) {
+                    this.flash("No workflow to cancel");
+                    return;
+                }
+                this.onForwardAction?.(buildWorkflowActionText(action, workflowId, undefined));
+                return;
+            }
+            this.flash("Select a stage row first");
+            return;
+        }
+        this.onForwardAction?.(buildWorkflowActionText(action, selected.stage.workflowId, selected.stage.stageId));
+    }
+    handleInput(keyData) {
+        const kb = getKeybindings();
+        if (kb.matches(keyData, "tui.select.cancel")) {
+            this.onClose?.();
+        }
+        else if (kb.matches(keyData, "tui.input.tab") || keyData === "l") {
+            this.toggleMode();
+        }
+        else if (kb.matches(keyData, "tui.select.up") || keyData === "k") {
+            this.move(-1);
+        }
+        else if (kb.matches(keyData, "tui.select.down") || keyData === "j") {
+            this.move(1);
+        }
+        else if (kb.matches(keyData, "tui.select.pageUp")) {
+            this.move(-Math.max(1, this.config.maxRows));
+        }
+        else if (kb.matches(keyData, "tui.select.pageDown")) {
+            this.move(Math.max(1, this.config.maxRows));
+        }
+        else if (keyData === "a") {
+            this.forward("approve");
+        }
+        else if (keyData === "r") {
+            this.forward("reject");
+        }
+        else if (keyData === "s") {
+            this.forward("skip");
+        }
+        else if (keyData === "c") {
+            this.forward("cancel");
+        }
+    }
+}
+//# sourceMappingURL=workflow-view.js.map