@ai-agent-forge/agent-forge 0.86.4 → 0.86.6

package/dist/modes/interactive/components/workflow-view.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 } from "@agent-forge/tui";
+import type { SessionEntry } from "../../../core/session-manager.ts";
+type StageStatus = "pending" | "active" | "awaiting_review" | "completed" | "failed" | "skipped";
+/** One selectable stage row of the L2 panorama tree. */
+export interface WorkflowStageRow {
+    workflowId: string;
+    stageId: string;
+    title: string;
+    depth: number;
+    status: StageStatus;
+    /** §8.1 waiting-condition label, or null when nothing blocks the stage. */
+    waitingOn: string | null;
+    attempts: number;
+    evidenceCount: number;
+    /** Conflicting active write stage id (write-scope marker), or null. */
+    scopeConflict: string | null;
+    /** Diamond edge collapsed to a back-reference instead of a duplicate subtree. */
+    backReference: boolean;
+}
+/** One workflow block of the L2 panorama. */
+export interface WorkflowBlock {
+    workflowId: string;
+    title: string;
+    status: string;
+    revision: number;
+    goalId: string | undefined;
+    activeCount: number;
+    maxActiveStages: number;
+    retreatCount: number;
+    maxRetreats: number;
+    diagnostics: string[];
+    stages: WorkflowStageRow[];
+}
+/** One L3 transition row (already newest-first, capped by the builder). */
+export interface WorkflowTransitionRow {
+    revision: number;
+    workflowId: string;
+    stageId: string | undefined;
+    from: string;
+    to: string;
+    trigger: string;
+    code: string;
+    message: string;
+    detail: string | undefined;
+}
+export interface WorkflowViewModel {
+    /** Undefined when the session has no `workflow.state` entry at all. */
+    panorama: WorkflowBlock[] | undefined;
+    transitions: WorkflowTransitionRow[];
+    /** Newest non-terminal workflow id (footer's pick), for workflow-level actions. */
+    activeWorkflowId: string | undefined;
+}
+/**
+ * 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 declare function buildWorkflowViewModel(entries: readonly SessionEntry[], transitionLimit?: number): WorkflowViewModel;
+/** Forwarded action vocabulary (§9 L2): rendered here, executed via workflow_advance by the main agent. */
+export type WorkflowForwardAction = "approve" | "reject" | "skip" | "cancel";
+/** Action text injected into the conversation input, e.g. `approve stage s2-review`. */
+export declare function buildWorkflowActionText(action: WorkflowForwardAction, workflowId: string, stageId: string | undefined): string;
+export interface WorkflowViewConfig {
+    /** Entries provider; rescanned when the array identity or length changes (append-only sessions). */
+    getEntries: () => readonly SessionEntry[];
+    /** Maximum visible rows before the list scrolls. */
+    maxRows: number;
+    /** Request a TUI re-render (used for transient status flashes). */
+    requestRender?: () => void;
+}
+export declare class WorkflowViewComponent extends Container {
+    onClose?: () => void;
+    onForwardAction?: (text: string) => void;
+    private config;
+    private mode;
+    private rows;
+    private selectedIndex;
+    private offset;
+    private titleText;
+    private modeHintText;
+    private helpText;
+    private flashText;
+    private cache;
+    private flashTimeout;
+    constructor(config: WorkflowViewConfig);
+    dispose(): void;
+    private updateModeTexts;
+    private buildHelpLine;
+    private getModel;
+    private buildRows;
+    private formatStageRow;
+    /** Rows are rebuilt lazily on access; the key couples rebuild + selection restore. */
+    private syncRows;
+    private clampOffset;
+    renderRows(width: number): string[];
+    private move;
+    private flash;
+    private toggleMode;
+    private forward;
+    handleInput(keyData: string): void;
+}
+export {};
+//# sourceMappingURL=workflow-view.d.ts.map

package/dist/modes/interactive/components/workflow-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-view.d.ts","sourceRoot":"","sources":["../../../../src/modes/interactive/components/workflow-view.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workflow overlay view (§9 L2/L3 of docs/design/工作流编排插件设计.md).\n *\n * Read-only panorama (L2) and transition stream (L3) rendered from the\n * session's `workflow.state` / `workflow.transition` custom entries — the\n * same isomorphic read the footer performs on `goal.state`, so the plugin\n * does not need to be present and this module never imports plugin code.\n * Waiting-condition labels mirror the engine's `computeWaitingOn` order\n * (active-limit precedes write-scope conflict); plan lookups read the latest\n * `plan.state` snapshot the same way.\n *\n * Operations are never executed here: approve/reject/skip/cancel forward an\n * action text (e.g. `approve stage s2-review`) to the conversation input and\n * the main agent drives it through workflow_advance — rendering and execution\n * stay separated (设计 §9 L2 \"转发到对话\").\n */\n\nimport { type Component, Container, getKeybindings, Text, truncateToWidth } from \"@agent-forge/tui\";\nimport type { SessionEntry } from \"../../../core/session-manager.ts\";\nimport { theme } from \"../theme/theme.ts\";\nimport { DynamicBorder } from \"./dynamic-border.ts\";\nimport { keyHint, rawKeyHint } from \"./keybinding-hints.ts\";\n\n// ---------------------------------------------------------------------------\n// View model (pure; exported for tests)\n// ---------------------------------------------------------------------------\n\ntype StageStatus = \"pending\" | \"active\" | \"awaiting_review\" | \"completed\" | \"failed\" | \"skipped\";\n\nconst STAGE_STATUSES: readonly string[] = [\"pending\", \"active\", \"awaiting_review\", \"completed\", \"failed\", \"skipped\"];\n\n/** One selectable stage row of the L2 panorama tree. */\nexport interface WorkflowStageRow {\n\tworkflowId: string;\n\tstageId: string;\n\ttitle: string;\n\tdepth: number;\n\tstatus: StageStatus;\n\t/** §8.1 waiting-condition label, or null when nothing blocks the stage. */\n\twaitingOn: string | null;\n\tattempts: number;\n\tevidenceCount: number;\n\t/** Conflicting active write stage id (write-scope marker), or null. */\n\tscopeConflict: string | null;\n\t/** Diamond edge collapsed to a back-reference instead of a duplicate subtree. */\n\tbackReference: boolean;\n}\n\n/** One workflow block of the L2 panorama. */\nexport interface WorkflowBlock {\n\tworkflowId: string;\n\ttitle: string;\n\tstatus: string;\n\trevision: number;\n\tgoalId: string | undefined;\n\tactiveCount: number;\n\tmaxActiveStages: number;\n\tretreatCount: number;\n\tmaxRetreats: number;\n\tdiagnostics: string[];\n\tstages: WorkflowStageRow[];\n}\n\n/** One L3 transition row (already newest-first, capped by the builder). */\nexport interface WorkflowTransitionRow {\n\trevision: number;\n\tworkflowId: string;\n\tstageId: string | undefined;\n\tfrom: string;\n\tto: string;\n\ttrigger: string;\n\tcode: string;\n\tmessage: string;\n\tdetail: string | undefined;\n}\n\nexport interface WorkflowViewModel {\n\t/** Undefined when the session has no `workflow.state` entry at all. */\n\tpanorama: WorkflowBlock[] | undefined;\n\ttransitions: WorkflowTransitionRow[];\n\t/** Newest non-terminal workflow id (footer's pick), for workflow-level actions. */\n\tactiveWorkflowId: string | undefined;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction stringOrUndefined(value: unknown): string | undefined {\n\treturn typeof value === \"string\" ? value : undefined;\n}\n\ninterface ParsedStageSpec {\n\tid: string;\n\ttitle: string;\n\tdependsOn: string[];\n\tplanId: string | undefined;\n\tkind: \"read\" | \"write\";\n\tscope: string[] | undefined;\n\tacceptanceIds: string[];\n}\n\ninterface ParsedStageRuntime {\n\tstageId: string;\n\tstatus: StageStatus;\n\tattempts: number;\n\tevidenceCount: number;\n\tcoveredAcceptanceIds: Set<string>;\n}\n\ninterface ParsedWorkflow {\n\tid: string;\n\ttitle: string;\n\tstatus: string;\n\trevision: number;\n\tgoalId: string | undefined;\n\tmaxActiveStages: number;\n\tmaxRetreats: number;\n\tretreatCount: number;\n\tdiagnostics: string[];\n\tstages: ParsedStageSpec[];\n\truntime: Map<string, ParsedStageRuntime>;\n}\n\nfunction parseStageSpec(value: unknown): ParsedStageSpec | undefined {\n\tif (!isRecord(value)) return undefined;\n\tconst id = stringOrUndefined(value.id);\n\tif (id === undefined) return undefined;\n\tconst dependsOn = Array.isArray(value.dependsOn) ? value.dependsOn.filter(isString) : [];\n\tconst acceptance =\n\t\tisRecord(value.objective) && Array.isArray(value.objective.acceptance) ? value.objective.acceptance : [];\n\tconst scope = Array.isArray(value.scope) ? value.scope.filter(isString) : undefined;\n\treturn {\n\t\tid,\n\t\ttitle: stringOrUndefined(value.title) ?? id,\n\t\tdependsOn,\n\t\tplanId: stringOrUndefined(value.planId),\n\t\tkind: value.kind === \"read\" ? \"read\" : \"write\",\n\t\tscope: scope !== undefined && scope.length > 0 ? scope : undefined,\n\t\tacceptanceIds: acceptance\n\t\t\t.map((item) => (isRecord(item) ? stringOrUndefined(item.id) : undefined))\n\t\t\t.filter((item): item is string => item !== undefined),\n\t};\n}\n\nfunction isString(value: unknown): value is string {\n\treturn typeof value === \"string\";\n}\n\nfunction parseStageRuntime(value: unknown): ParsedStageRuntime | undefined {\n\tif (!isRecord(value)) return undefined;\n\tconst stageId = stringOrUndefined(value.stageId);\n\tconst status = stringOrUndefined(value.status);\n\tif (stageId === undefined || status === undefined || !STAGE_STATUSES.includes(status)) return undefined;\n\tconst evidence = Array.isArray(value.evidence) ? value.evidence : [];\n\tconst covered = new Set<string>();\n\tlet evidenceCount = 0;\n\tfor (const item of evidence) {\n\t\tif (!isRecord(item)) continue;\n\t\tevidenceCount++;\n\t\tconst acceptanceId = stringOrUndefined(item.acceptanceId);\n\t\tif (acceptanceId !== undefined) covered.add(acceptanceId);\n\t}\n\treturn {\n\t\tstageId,\n\t\tstatus: status as StageStatus,\n\t\tattempts: typeof value.attempts === \"number\" ? value.attempts : 0,\n\t\tevidenceCount,\n\t\tcoveredAcceptanceIds: covered,\n\t};\n}\n\nfunction parseWorkflowRecord(value: unknown): ParsedWorkflow | undefined {\n\tif (!isRecord(value)) return undefined;\n\tconst id = stringOrUndefined(value.id);\n\tconst title = stringOrUndefined(value.title);\n\tconst status = stringOrUndefined(value.status);\n\tif (id === undefined || title === undefined || status === undefined) return undefined;\n\tconst stages: ParsedStageSpec[] = [];\n\tfor (const item of Array.isArray(value.stages) ? value.stages : []) {\n\t\tconst spec = parseStageSpec(item);\n\t\tif (spec !== undefined) stages.push(spec);\n\t}\n\tconst runtime = new Map<string, ParsedStageRuntime>();\n\tfor (const item of Array.isArray(value.runtime) ? value.runtime : []) {\n\t\tconst parsed = parseStageRuntime(item);\n\t\tif (parsed !== undefined) runtime.set(parsed.stageId, parsed);\n\t}\n\tconst diagnostics = Array.isArray(value.diagnostics) ? value.diagnostics.filter(isString) : [];\n\treturn {\n\t\tid,\n\t\ttitle,\n\t\tstatus,\n\t\trevision: typeof value.revision === \"number\" ? value.revision : 0,\n\t\tgoalId: stringOrUndefined(value.goalId),\n\t\tmaxActiveStages: typeof value.maxActiveStages === \"number\" ? value.maxActiveStages : 4,\n\t\tmaxRetreats: typeof value.maxRetreats === \"number\" ? value.maxRetreats : 3,\n\t\tretreatCount: typeof value.retreatCount === \"number\" ? value.retreatCount : 0,\n\t\tdiagnostics,\n\t\tstages,\n\t\truntime,\n\t};\n}\n\n/** Latest `plan.state` snapshot reduced to id -> status (plan-dangling / plan-incomplete labels). */\nfunction parsePlanStatuses(data: unknown): Map<string, string> {\n\tconst statuses = new Map<string, string>();\n\tif (!isRecord(data) || !Array.isArray(data.plans)) return statuses;\n\tfor (const item of data.plans) {\n\t\tif (!isRecord(item)) continue;\n\t\tconst id = stringOrUndefined(item.id);\n\t\tconst status = stringOrUndefined(item.status);\n\t\tif (id !== undefined && status !== undefined) statuses.set(id, status);\n\t}\n\treturn statuses;\n}\n\nfunction parseTransition(value: unknown): WorkflowTransitionRow | undefined {\n\tif (!isRecord(value)) return undefined;\n\tconst workflowId = stringOrUndefined(value.workflowId);\n\tconst from = stringOrUndefined(value.from);\n\tconst to = stringOrUndefined(value.to);\n\tconst reason = isRecord(value.reason) ? value.reason : undefined;\n\tconst code = reason !== undefined ? stringOrUndefined(reason.code) : undefined;\n\tif (\n\t\tworkflowId === undefined ||\n\t\tfrom === undefined ||\n\t\tto === undefined ||\n\t\tcode === undefined ||\n\t\ttypeof value.revision !== \"number\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\trevision: value.revision,\n\t\tworkflowId,\n\t\tstageId: stringOrUndefined(value.stageId),\n\t\tfrom,\n\t\tto,\n\t\ttrigger: stringOrUndefined(value.trigger) ?? \"tool\",\n\t\tcode,\n\t\tmessage: reason !== undefined ? (stringOrUndefined(reason.message) ?? \"\") : \"\",\n\t\tdetail: reason !== undefined ? stringOrUndefined(reason.detail) : undefined,\n\t};\n}\n\nfunction scopesIntersect(a: string[] | undefined, b: string[] | undefined): boolean {\n\tif (a === undefined || a.length === 0 || b === undefined || b.length === 0) return true;\n\treturn a.some((tag) => b.includes(tag));\n}\n\nfunction findScopeConflict(workflow: ParsedWorkflow, spec: ParsedStageSpec): string | null {\n\tif (spec.kind !== \"write\") return null;\n\tfor (const other of workflow.stages) {\n\t\tif (other.id === spec.id || other.kind !== \"write\") continue;\n\t\tif (workflow.runtime.get(other.id)?.status !== \"active\") continue;\n\t\tif (scopesIntersect(spec.scope, other.scope)) return other.id;\n\t}\n\treturn null;\n}\n\nfunction uncoveredAcceptanceIds(spec: ParsedStageSpec, runtime: ParsedStageRuntime | undefined): string[] {\n\tif (runtime === undefined) return [...spec.acceptanceIds];\n\treturn spec.acceptanceIds.filter((id) => !runtime.coveredAcceptanceIds.has(id));\n}\n\n/**\n * §8.1 waiting-condition label, mirroring the engine's `computeWaitingOn`\n * check order (active-limit precedes write-scope conflict) so the overlay\n * names the same condition the audit stream recorded. Plan lookups use the\n * latest `plan.state` snapshot instead of the engine's live dependency.\n */\nfunction computeWaitingOn(\n\tworkflow: ParsedWorkflow,\n\tspec: ParsedStageSpec,\n\truntime: ParsedStageRuntime | undefined,\n\tplanStatuses: Map<string, string>,\n): string | null {\n\tconst status = runtime?.status ?? \"pending\";\n\tif (status === \"awaiting_review\") return \"review\";\n\tif (status === \"pending\") {\n\t\tif (workflow.status === \"draft\") return \"not-yet-active\";\n\t\tif ((runtime?.attempts ?? 0) > 0) {\n\t\t\tif (spec.acceptanceIds.length === 0) return \"retry-wait\";\n\t\t\treturn `acceptance-missing:[${uncoveredAcceptanceIds(spec, runtime).join(\", \")}]`;\n\t\t}\n\t\tconst incomplete = spec.dependsOn.filter((dep) => {\n\t\t\tconst dependency = workflow.runtime.get(dep)?.status;\n\t\t\treturn dependency !== \"completed\" && dependency !== \"skipped\";\n\t\t});\n\t\tif (incomplete.length > 0) return `deps-incomplete:[${incomplete.join(\", \")}]`;\n\t\tif (spec.planId !== undefined && !planStatuses.has(spec.planId)) return \"plan-dangling\";\n\t\tconst activeCount = [...workflow.runtime.values()].filter((item) => item.status === \"active\").length;\n\t\tif (activeCount >= workflow.maxActiveStages) return \"active-limit\";\n\t\tconst conflict = findScopeConflict(workflow, spec);\n\t\tif (conflict !== null) return `write-scope-conflict:[${conflict}]`;\n\t\treturn \"not-yet-active\";\n\t}\n\tif (status === \"active\") {\n\t\tif (spec.planId === undefined) return null;\n\t\tconst planStatus = planStatuses.get(spec.planId);\n\t\tif (planStatus === undefined) return \"plan-dangling\";\n\t\tif (planStatus !== \"completed\") return \"plan-incomplete\";\n\t\treturn null;\n\t}\n\treturn null;\n}\n\nfunction buildStageRows(workflow: ParsedWorkflow, planStatuses: Map<string, string>): WorkflowStageRow[] {\n\tconst rows: WorkflowStageRow[] = [];\n\tconst visited = new Set<string>();\n\tconst walk = (spec: ParsedStageSpec, depth: number): void => {\n\t\tif (visited.has(spec.id)) {\n\t\t\trows.push({\n\t\t\t\tworkflowId: workflow.id,\n\t\t\t\tstageId: spec.id,\n\t\t\t\ttitle: spec.title,\n\t\t\t\tdepth,\n\t\t\t\tstatus: workflow.runtime.get(spec.id)?.status ?? \"pending\",\n\t\t\t\twaitingOn: null,\n\t\t\t\tattempts: 0,\n\t\t\t\tevidenceCount: 0,\n\t\t\t\tscopeConflict: null,\n\t\t\t\tbackReference: true,\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tvisited.add(spec.id);\n\t\tconst runtime = workflow.runtime.get(spec.id);\n\t\trows.push({\n\t\t\tworkflowId: workflow.id,\n\t\t\tstageId: spec.id,\n\t\t\ttitle: spec.title,\n\t\t\tdepth,\n\t\t\tstatus: runtime?.status ?? \"pending\",\n\t\t\twaitingOn: computeWaitingOn(workflow, spec, runtime, planStatuses),\n\t\t\tattempts: runtime?.attempts ?? 0,\n\t\t\tevidenceCount: runtime?.evidenceCount ?? 0,\n\t\t\tscopeConflict: findScopeConflict(workflow, spec),\n\t\t\tbackReference: false,\n\t\t});\n\t\tfor (const child of workflow.stages.filter((item) => item.dependsOn.includes(spec.id))) {\n\t\t\twalk(child, depth + 1);\n\t\t}\n\t};\n\tfor (const root of workflow.stages.filter((item) => item.dependsOn.length === 0)) {\n\t\twalk(root, 0);\n\t}\n\t// Stages unreachable from a root (defensive; the engine validates acyclic\n\t// graphs) still render at the top level, mirroring the L1 text panorama.\n\tfor (const spec of workflow.stages) {\n\t\tif (!visited.has(spec.id)) walk(spec, 0);\n\t}\n\treturn rows;\n}\n\n/**\n * Build the L2/L3 view model from session entries: the latest\n * `workflow.state` snapshot plus the `workflow.transition` audit stream\n * (newest first, capped). Malformed records are skipped, never thrown.\n */\nexport function buildWorkflowViewModel(entries: readonly SessionEntry[], transitionLimit = 30): WorkflowViewModel {\n\tlet stateData: unknown;\n\tlet hasStateEntry = false;\n\tlet planData: unknown;\n\tconst transitions: WorkflowTransitionRow[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\") continue;\n\t\tif (entry.customType === \"workflow.state\") {\n\t\t\thasStateEntry = true;\n\t\t\tstateData = entry.data;\n\t\t} else if (entry.customType === \"plan.state\") {\n\t\t\tplanData = entry.data;\n\t\t} else if (entry.customType === \"workflow.transition\") {\n\t\t\tconst parsed = parseTransition(entry.data);\n\t\t\tif (parsed !== undefined) transitions.push(parsed);\n\t\t}\n\t}\n\n\tconst planStatuses = parsePlanStatuses(planData);\n\tlet blocks: WorkflowBlock[] | undefined;\n\tif (hasStateEntry) {\n\t\tconst workflows = isRecord(stateData) && Array.isArray(stateData.workflows) ? stateData.workflows : [];\n\t\tblocks = workflows\n\t\t\t.map((item) => {\n\t\t\t\tconst parsed = parseWorkflowRecord(item);\n\t\t\t\tif (parsed === undefined) return undefined;\n\t\t\t\treturn {\n\t\t\t\t\tworkflowId: parsed.id,\n\t\t\t\t\ttitle: parsed.title,\n\t\t\t\t\tstatus: parsed.status,\n\t\t\t\t\trevision: parsed.revision,\n\t\t\t\t\tgoalId: parsed.goalId,\n\t\t\t\t\tactiveCount: [...parsed.runtime.values()].filter((item) => item.status === \"active\").length,\n\t\t\t\t\tmaxActiveStages: parsed.maxActiveStages,\n\t\t\t\t\tretreatCount: parsed.retreatCount,\n\t\t\t\t\tmaxRetreats: parsed.maxRetreats,\n\t\t\t\t\tdiagnostics: [...parsed.diagnostics],\n\t\t\t\t\tstages: buildStageRows(parsed, planStatuses),\n\t\t\t\t} satisfies WorkflowBlock;\n\t\t\t})\n\t\t\t.filter((block): block is WorkflowBlock => block !== undefined);\n\t}\n\n\tconst activeRecord = blocks?.filter((block) => block.status === \"draft\" || block.status === \"running\").at(-1);\n\tconst activeWorkflowId = activeRecord?.workflowId ?? blocks?.at(-1)?.workflowId;\n\n\treturn {\n\t\tpanorama: blocks,\n\t\ttransitions: transitions.slice(-transitionLimit).reverse(),\n\t\tactiveWorkflowId,\n\t};\n}\n\n/** Forwarded action vocabulary (§9 L2): rendered here, executed via workflow_advance by the main agent. */\nexport type WorkflowForwardAction = \"approve\" | \"reject\" | \"skip\" | \"cancel\";\n\n/** Action text injected into the conversation input, e.g. `approve stage s2-review`. */\nexport function buildWorkflowActionText(\n\taction: WorkflowForwardAction,\n\tworkflowId: string,\n\tstageId: string | undefined,\n): string {\n\tif (action === \"cancel\" || stageId === undefined) return `cancel workflow ${workflowId}`;\n\treturn `${action} stage ${stageId}`;\n}\n\n// ---------------------------------------------------------------------------\n// Component (L2 panorama + L3 log)\n// ---------------------------------------------------------------------------\n\n/** Selectable row shape used by the component; stage rows carry action targets. */\ninterface ViewRow {\n\ttext: string;\n\tstage: { workflowId: string; stageId: string } | undefined;\n}\n\nfunction stageStatusColor(status: StageStatus): (text: string) => string {\n\tswitch (status) {\n\t\tcase \"active\":\n\t\t\treturn (text) => theme.fg(\"accent\", text);\n\t\tcase \"awaiting_review\":\n\t\t\treturn (text) => theme.fg(\"warning\", text);\n\t\tcase \"completed\":\n\t\t\treturn (text) => theme.fg(\"success\", text);\n\t\tcase \"failed\":\n\t\t\treturn (text) => theme.fg(\"error\", text);\n\t\tcase \"skipped\":\n\t\t\treturn (text) => theme.fg(\"dim\", text);\n\t\tcase \"pending\":\n\t\t\treturn (text) => theme.fg(\"muted\", text);\n\t}\n}\n\nfunction workflowStatusColor(status: string): (text: string) => string {\n\tif (status === \"running\") return (text) => theme.fg(\"accent\", text);\n\tif (status === \"completed\") return (text) => theme.fg(\"success\", text);\n\tif (status === \"failed\") return (text) => theme.fg(\"error\", text);\n\treturn (text) => theme.fg(\"dim\", text);\n}\n\nfunction transitionCodeColor(code: string): (text: string) => string {\n\tif (code.includes(\"failed\") || code.includes(\"retreat\") || code.includes(\"error\") || code.includes(\"limit\")) {\n\t\treturn (text) => theme.fg(\"error\", text);\n\t}\n\tif (code.includes(\"held\") || code.includes(\"retry\") || code.includes(\"amended\")) {\n\t\treturn (text) => theme.fg(\"warning\", text);\n\t}\n\treturn (text) => theme.fg(\"muted\", text);\n}\n\n/** Renders the visible row window; reads live state from the owning component. */\nclass WorkflowRowsView implements Component {\n\tprivate view: WorkflowViewComponent;\n\n\tconstructor(view: WorkflowViewComponent) {\n\t\tthis.view = view;\n\t}\n\n\tinvalidate(): void {}\n\n\trender(width: number): string[] {\n\t\treturn this.view.renderRows(width);\n\t}\n}\n\nexport interface WorkflowViewConfig {\n\t/** Entries provider; rescanned when the array identity or length changes (append-only sessions). */\n\tgetEntries: () => readonly SessionEntry[];\n\t/** Maximum visible rows before the list scrolls. */\n\tmaxRows: number;\n\t/** Request a TUI re-render (used for transient status flashes). */\n\trequestRender?: () => void;\n}\n\nexport class WorkflowViewComponent extends Container {\n\tpublic onClose?: () => void;\n\tpublic onForwardAction?: (text: string) => void;\n\n\tprivate config: WorkflowViewConfig;\n\tprivate mode: \"panorama\" | \"log\" = \"panorama\";\n\tprivate rows: ViewRow[] = [];\n\tprivate selectedIndex = 0;\n\tprivate offset = 0;\n\tprivate titleText: Text;\n\tprivate modeHintText: Text;\n\tprivate helpText: Text;\n\tprivate flashText: Text;\n\tprivate cache: { entries: readonly SessionEntry[]; length: number; model: WorkflowViewModel } | undefined;\n\tprivate flashTimeout: ReturnType<typeof setTimeout> | null = null;\n\n\tconstructor(config: WorkflowViewConfig) {\n\t\tsuper();\n\n\t\tthis.config = config;\n\t\tthis.titleText = new Text(theme.fg(\"accent\", theme.bold(\"  Workflow Overview\")), 1, 0);\n\t\tthis.modeHintText = new Text(\"\", 1, 0);\n\t\tthis.helpText = new Text(\"\", 1, 0);\n\t\tthis.flashText = new Text(\"\", 1, 0);\n\t\tthis.updateModeTexts();\n\n\t\tthis.addChild(new DynamicBorder());\n\t\tthis.addChild(this.titleText);\n\t\tthis.addChild(this.modeHintText);\n\t\tthis.addChild(new WorkflowRowsView(this));\n\t\tthis.addChild(this.flashText);\n\t\tthis.addChild(this.helpText);\n\t\tthis.addChild(new DynamicBorder());\n\t}\n\n\tdispose(): void {\n\t\tif (this.flashTimeout !== null) {\n\t\t\tclearTimeout(this.flashTimeout);\n\t\t\tthis.flashTimeout = null;\n\t\t}\n\t}\n\n\tprivate updateModeTexts(): void {\n\t\tconst label = this.mode === \"panorama\" ? \"panorama\" : \"transition log (newest first)\";\n\t\tthis.modeHintText.setText(theme.fg(\"dim\", `  ${label}`));\n\t\tthis.helpText.setText(this.buildHelpLine());\n\t}\n\n\tprivate buildHelpLine(): string {\n\t\tconst parts = [rawKeyHint(\"↑↓\", \"move\")];\n\t\tif (this.mode === \"panorama\") {\n\t\t\tparts.push(\n\t\t\t\trawKeyHint(\"tab/l\", \"log\"),\n\t\t\t\trawKeyHint(\"a\", \"approve\"),\n\t\t\t\trawKeyHint(\"r\", \"reject\"),\n\t\t\t\trawKeyHint(\"s\", \"skip\"),\n\t\t\t\trawKeyHint(\"c\", \"cancel\"),\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(rawKeyHint(\"tab/l\", \"panorama\"));\n\t\t}\n\t\tparts.push(keyHint(\"tui.select.cancel\", \"close\"));\n\t\treturn `  ${parts.join(\"  \")}`;\n\t}\n\n\tprivate getModel(): WorkflowViewModel {\n\t\tconst entries = this.config.getEntries();\n\t\tif (this.cache && this.cache.entries === entries && this.cache.length === entries.length) {\n\t\t\treturn this.cache.model;\n\t\t}\n\t\tconst model = buildWorkflowViewModel(entries);\n\t\tthis.cache = { entries, length: entries.length, model };\n\t\treturn model;\n\t}\n\n\tprivate buildRows(model: WorkflowViewModel): ViewRow[] {\n\t\tconst rows: ViewRow[] = [];\n\t\tif (this.mode === \"log\") {\n\t\t\tif (model.transitions.length === 0) {\n\t\t\t\trows.push({ text: \"  no workflow transitions recorded\", stage: undefined });\n\t\t\t\treturn rows;\n\t\t\t}\n\t\t\tfor (const transition of model.transitions) {\n\t\t\t\tconst stage = transition.stageId !== undefined ? `/${transition.stageId}` : \"\";\n\t\t\t\tconst detail = transition.detail !== undefined ? ` — ${transition.detail}` : \"\";\n\t\t\t\tconst code = transitionCodeColor(transition.code)(transition.code);\n\t\t\t\trows.push({\n\t\t\t\t\ttext: `  #${transition.revision} ${transition.workflowId}${stage} ${transition.from} -> ${transition.to} [${transition.trigger}] ${code}: ${transition.message}${detail}`,\n\t\t\t\t\tstage: undefined,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn rows;\n\t\t}\n\n\t\tconst blocks = model.panorama;\n\t\tif (blocks === undefined) {\n\t\t\trows.push({ text: \"  no workflow.state entry in this session\", stage: undefined });\n\t\t\treturn rows;\n\t\t}\n\t\tif (blocks.length === 0) {\n\t\t\trows.push({ text: \"  no workflows in this session; create one with workflow_set\", stage: undefined });\n\t\t\treturn rows;\n\t\t}\n\t\tfor (const block of blocks) {\n\t\t\tconst status = workflowStatusColor(block.status)(block.status);\n\t\t\trows.push({\n\t\t\t\ttext: `  workflow \"${block.title}\" (${block.workflowId}) — ${status} · revision ${block.revision} · active ${block.activeCount}/${block.maxActiveStages} · retreats ${block.retreatCount}/${block.maxRetreats}`,\n\t\t\t\tstage: undefined,\n\t\t\t});\n\t\t\tif (block.goalId !== undefined) {\n\t\t\t\trows.push({ text: `    goal: ${block.goalId}`, stage: undefined });\n\t\t\t}\n\t\t\tfor (const stage of block.stages) {\n\t\t\t\trows.push({\n\t\t\t\t\ttext: this.formatStageRow(stage),\n\t\t\t\t\tstage: { workflowId: block.workflowId, stageId: stage.stageId },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (block.diagnostics.length > 0) {\n\t\t\t\trows.push({ text: \"    diagnostics:\", stage: undefined });\n\t\t\t\tfor (const diagnostic of block.diagnostics) {\n\t\t\t\t\trows.push({ text: theme.fg(\"warning\", `      - ${diagnostic}`), stage: undefined });\n\t\t\t\t}\n\t\t\t}\n\t\t\trows.push({ text: \"\", stage: undefined });\n\t\t}\n\t\treturn rows;\n\t}\n\n\tprivate formatStageRow(stage: WorkflowStageRow): string {\n\t\tconst pad = \"  \".repeat(stage.depth + 1);\n\t\tif (stage.backReference) {\n\t\t\treturn `${pad}  -> ${stage.stageId} (shown above)`;\n\t\t}\n\t\tconst bits = [`- ${stage.stageId} [${stageStatusColor(stage.status)(stage.status)}] ${stage.title}`];\n\t\tif (stage.waitingOn !== null) bits.push(theme.fg(\"dim\", `— waiting: ${stage.waitingOn}`));\n\t\tif (stage.attempts > 0) bits.push(theme.fg(\"dim\", `· attempts ${stage.attempts}`));\n\t\tif (stage.evidenceCount > 0) bits.push(theme.fg(\"dim\", `· evidence ${stage.evidenceCount}`));\n\t\tif (stage.scopeConflict !== null) {\n\t\t\tbits.push(theme.fg(\"warning\", `⚠ scope:${stage.scopeConflict}`));\n\t\t}\n\t\treturn `${pad}${bits.join(\" \")}`;\n\t}\n\n\t/** Rows are rebuilt lazily on access; the key couples rebuild + selection restore. */\n\tprivate syncRows(): void {\n\t\tconst model = this.getModel();\n\t\tconst previous = this.rows[this.selectedIndex]?.stage;\n\t\tthis.rows = this.buildRows(model);\n\t\tif (previous !== undefined) {\n\t\t\tconst restored = this.rows.findIndex((row) => row.stage?.stageId === previous.stageId);\n\t\t\tif (restored !== -1) this.selectedIndex = restored;\n\t\t}\n\t\tif (this.selectedIndex >= this.rows.length) this.selectedIndex = Math.max(0, this.rows.length - 1);\n\t\tthis.clampOffset();\n\t}\n\n\tprivate clampOffset(): void {\n\t\tconst maxRows = Math.max(1, this.config.maxRows);\n\t\tif (this.selectedIndex < this.offset) this.offset = this.selectedIndex;\n\t\tif (this.selectedIndex >= this.offset + maxRows) this.offset = this.selectedIndex - maxRows + 1;\n\t\tif (this.offset < 0) this.offset = 0;\n\t}\n\n\trenderRows(width: number): string[] {\n\t\tthis.syncRows();\n\t\tconst maxRows = Math.max(1, this.config.maxRows);\n\t\tconst lines: string[] = [];\n\t\tfor (let index = this.offset; index < Math.min(this.rows.length, this.offset + maxRows); index++) {\n\t\t\tconst row = this.rows[index];\n\t\t\tif (row === undefined) continue;\n\t\t\tconst selected = index === this.selectedIndex;\n\t\t\tconst prefix = selected ? theme.fg(\"accent\", \"→ \") : \"  \";\n\t\t\tlines.push(truncateToWidth(`${prefix}${row.text}`, width));\n\t\t}\n\t\tconst hiddenAbove = this.offset;\n\t\tconst hiddenBelow = this.rows.length - this.offset - maxRows;\n\t\tconst hidden: string[] = [];\n\t\tif (hiddenAbove > 0) hidden.push(`↑${hiddenAbove}`);\n\t\tif (hiddenBelow > 0) hidden.push(`↓${hiddenBelow}`);\n\t\t// Fixed output height (exactly maxRows content rows plus this final\n\t\t// indicator row), the same contract as agents-view renderRows: the\n\t\t// overlay's grid footprint must not change with mode switches or row\n\t\t// counts, or the chat/editor layout boundary moves between frames.\n\t\twhile (lines.length < maxRows) lines.push(truncateToWidth(\" \", width));\n\t\tlines.push(truncateToWidth(hidden.length > 0 ? theme.fg(\"dim\", `  ${hidden.join(\" \")}`) : \" \", width));\n\t\treturn lines;\n\t}\n\n\tprivate move(delta: number): void {\n\t\tif (this.rows.length === 0) return;\n\t\tthis.selectedIndex = Math.min(this.rows.length - 1, Math.max(0, this.selectedIndex + delta));\n\t\tthis.clampOffset();\n\t}\n\n\tprivate flash(message: string): void {\n\t\tthis.flashText.setText(theme.fg(\"warning\", `  ${message}`));\n\t\tif (this.flashTimeout !== null) clearTimeout(this.flashTimeout);\n\t\tthis.flashTimeout = setTimeout(() => {\n\t\t\tthis.flashText.setText(\"\");\n\t\t\tthis.flashTimeout = null;\n\t\t\tthis.config.requestRender?.();\n\t\t}, 2500);\n\t\tthis.config.requestRender?.();\n\t}\n\n\tprivate toggleMode(): void {\n\t\tthis.mode = this.mode === \"panorama\" ? \"log\" : \"panorama\";\n\t\tthis.selectedIndex = 0;\n\t\tthis.offset = 0;\n\t\tthis.updateModeTexts();\n\t\tthis.config.requestRender?.();\n\t}\n\n\tprivate forward(action: WorkflowForwardAction): void {\n\t\tconst selected = this.rows[this.selectedIndex];\n\t\tif (selected?.stage === undefined) {\n\t\t\tif (action === \"cancel\") {\n\t\t\t\tconst workflowId = this.getModel().activeWorkflowId;\n\t\t\t\tif (workflowId === undefined) {\n\t\t\t\t\tthis.flash(\"No workflow to cancel\");\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tthis.onForwardAction?.(buildWorkflowActionText(action, workflowId, undefined));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tthis.flash(\"Select a stage row first\");\n\t\t\treturn;\n\t\t}\n\t\tthis.onForwardAction?.(buildWorkflowActionText(action, selected.stage.workflowId, selected.stage.stageId));\n\t}\n\n\thandleInput(keyData: string): void {\n\t\tconst kb = getKeybindings();\n\t\tif (kb.matches(keyData, \"tui.select.cancel\")) {\n\t\t\tthis.onClose?.();\n\t\t} else if (kb.matches(keyData, \"tui.input.tab\") || keyData === \"l\") {\n\t\t\tthis.toggleMode();\n\t\t} else if (kb.matches(keyData, \"tui.select.up\") || keyData === \"k\") {\n\t\t\tthis.move(-1);\n\t\t} else if (kb.matches(keyData, \"tui.select.down\") || keyData === \"j\") {\n\t\t\tthis.move(1);\n\t\t} else if (kb.matches(keyData, \"tui.select.pageUp\")) {\n\t\t\tthis.move(-Math.max(1, this.config.maxRows));\n\t\t} else if (kb.matches(keyData, \"tui.select.pageDown\")) {\n\t\t\tthis.move(Math.max(1, this.config.maxRows));\n\t\t} else if (keyData === \"a\") {\n\t\t\tthis.forward(\"approve\");\n\t\t} else if (keyData === \"r\") {\n\t\t\tthis.forward(\"reject\");\n\t\t} else if (keyData === \"s\") {\n\t\t\tthis.forward(\"skip\");\n\t\t} else if (keyData === \"c\") {\n\t\t\tthis.forward(\"cancel\");\n\t\t}\n\t}\n}\n"]}