flow/render/live

Source: src/flow/render/live.ts

The live view of a flow run: its plan, filled from the journal and the event stream, folded by the state of each visit.

A visit running now is expanded, one that ended is one line saying how, and one not made yet is its plan line. Every iteration a loop ran, every map item and every parallel branch keeps a line while its block runs, folded once it ended. A running call expands its callee’s plan under it. A choice’s cases are one line until it decides, case 1, default, then the case it took and one line for the ones it did not. A node its sequence never reached, a failure or a stop having ended it, keeps its line with nothing more.

It is a pure fold, like picture.ts beside it: the same journal and events give the same frame, and nothing here draws.

LiveLine

type

export type LiveLine = {
	/** A plan line's kind, an iteration, a `map` item, or the cases of a `choice` it did not take. */
	readonly kind: PlanLine["kind"] | "iteration" | "item" | "cases";
	/** What the line is called: its visit path, `case 1`, `default`, or the cases it folds. */
	readonly label: string;
	/** The visit path; a case keeps its choice's, and a pending line inside a block its plan's `#n` and `[i]`. */
	readonly path: string;
	/** Where the visit stands: pending, running, blocked, done, failed or never reached. */
	readonly state: LiveState;
	/** The plan's facts while pending, what is under way while running, and how it ended once over. */
	readonly facts: readonly string[];
	/** The plan's bound, while pending. */
	readonly bound?: PlanLine["bound"];
	/** What it cost, once over, in every life that ran it: `wallMs` is its time. */
	readonly usage?: Usage;
	/** The subagents spawned for an `agent` visit. */
	readonly subagents: readonly string[];
	/** The lines under it: a block's sequence, a loop's iterations, a map's items. */
	readonly lines: readonly LiveLine[];
};

One line of the live view, and the lines under it.

livePlan

function

export function livePlan(checked: CheckedFlow, journal: readonly JournalEntry[], events: readonly SubagentEvent[], elapsedMs?: number): LivePlan { /* … */ }

The live view of the run of checked: journal is what its earlier lives wrote, events what this one told. A finished run’s journal alone draws its last frame, and a live run’s events alone draw it as it goes.

elapsedMs is how long this life has run, by the caller’s clock, while it runs: the summary’s time, which the visits it ended cannot give. The fold reads no clock of its own, so the same arguments draw the same frame.

LivePlan

type

export type LivePlan = {
	/** The flow's name. */
	readonly flow: string;
	/** What the summary line says. */
	readonly summary: LiveSummary;
	/** The root sequence. */
	readonly lines: readonly LiveLine[];
};

A run’s live view: the flow, the one-line summary, and its root sequence.

LiveState

type

export type LiveState = "pending" | "working" | "blocked" | "done" | "failed" | "unreached";

Where a line stands. working, blocked (an ask waiting for its answer), done and failed are a subagent’s standings too; pending is not visited yet, and unreached never will be in this life.