@corbits/react-ui 0.1.0

package/dist/lib/workflow-display-flow.d.ts

@@ -0,0 +1,83 @@
+import type { StepDisplayStatus, StepListItem } from "./workflow-registry.js";
+/**
+ * How a display step behaves at runtime — a renderer-facing vocabulary for
+ * drawing a gate differently from a sleep differently from a child-workflow
+ * spawn, independent of whatever primitive-kind enum the host's workflow
+ * engine uses internally.
+ */
+export type DisplayStepCharacter = "deterministic" | "reasoning" | "gate" | "await" | "action" | "sleep" | "child" | "other";
+/** One display step derived from a single runtime primitive. `after` is
+ * carried through unmodified so a renderer can lay out parallel branches
+ * honestly instead of flattening the DAG into a single line. */
+export type DisplayFlowStep = {
+    readonly stepId: string;
+    readonly label: string;
+    readonly character: DisplayStepCharacter;
+    readonly after: readonly string[];
+};
+/** The full derived display model for one workflow definition, already in
+ * run order. */
+export type DisplayFlow = {
+    readonly steps: readonly DisplayFlowStep[];
+};
+/**
+ * What `deriveDisplayFlow` needs to know about one runtime primitive. The
+ * host's workflow engine owns the real primitive-kind enum and any
+ * author-tagging convention for a friendlier label or a deterministic flag —
+ * this shape asks the host to resolve those once, at the boundary, rather
+ * than importing the host's tag vocabulary in here.
+ */
+export type WorkflowStepPrimitive = {
+    readonly stepId: string;
+    readonly kind: "step" | "map" | "gate" | "awaitSignal" | "escalation" | "sleep" | "childWorkflow" | "action" | "other";
+    /** Already-humanised label. The step id is used verbatim when omitted. */
+    readonly label?: string;
+    readonly after?: readonly string[];
+    /** True for a `step`/`map` primitive the host tags as deterministic tool
+     * work rather than a model call — everything else defaults to `reasoning`. */
+    readonly deterministic?: boolean;
+};
+/**
+ * Projects a workflow's runtime primitives into one display step per
+ * primitive, in the order given. The host resolves each primitive's label
+ * and deterministic flag before calling this — that keeps any
+ * author-tagging convention (a legacy tag, a metadata field) out of a
+ * published library, where the tag vocabulary would become part of the
+ * public surface.
+ */
+export declare function deriveDisplayFlow(primitives: readonly WorkflowStepPrimitive[]): DisplayFlow;
+/** A curated group of runtime steps, as declared by whoever authored the
+ * curation (a workflow author, a preview overlay). */
+export type DisplayOverlayGroup = {
+    readonly key: string;
+    readonly label: string;
+    readonly steps: readonly string[];
+    readonly activityLabel?: string;
+};
+export type DisplayOverlay = {
+    readonly groups: readonly DisplayOverlayGroup[];
+};
+/** One curated group after applying a `DisplayOverlay` to a `DisplayFlow`. */
+export type OverlaidDisplayStep = {
+    readonly key: string;
+    readonly label: string;
+    readonly character: DisplayStepCharacter;
+    readonly stepIds: readonly string[];
+    readonly activityLabel?: string;
+};
+export type OverlaidDisplayFlow = {
+    readonly groups: readonly OverlaidDisplayStep[];
+};
+/**
+ * Curates a derived `DisplayFlow` into an author's declared groups. Every
+ * group's `steps` is validated against the flow's actual step ids — an
+ * unknown id throws immediately rather than silently producing an empty or
+ * partial group.
+ */
+export declare function applyDisplayOverlay(flow: DisplayFlow, overlay: DisplayOverlay): OverlaidDisplayFlow;
+/**
+ * Maps pure display-flow steps into `StepList` items, all `pending` unless a
+ * status lookup is given — the host overlays real run state on top once it
+ * has any.
+ */
+export declare function stepListFromDisplayFlow(steps: readonly DisplayFlowStep[], statusById?: ReadonlyMap<string, StepDisplayStatus> | Record<string, StepDisplayStatus>): StepListItem[];

package/dist/lib/workflow-display-flow.js

@@ -0,0 +1,104 @@
+function characterOf(primitive) {
+    switch(primitive.kind){
+        case "step":
+        case "map":
+            return primitive.deterministic === true ? "deterministic" : "reasoning";
+        case "gate":
+            return "gate";
+        case "awaitSignal":
+        case "escalation":
+            return "await";
+        case "sleep":
+            return "sleep";
+        case "childWorkflow":
+            return "child";
+        case "action":
+            return "action";
+        default:
+            return "other";
+    }
+}
+/**
+ * Projects a workflow's runtime primitives into one display step per
+ * primitive, in the order given. The host resolves each primitive's label
+ * and deterministic flag before calling this — that keeps any
+ * author-tagging convention (a legacy tag, a metadata field) out of a
+ * published library, where the tag vocabulary would become part of the
+ * public surface.
+ */ export function deriveDisplayFlow(primitives) {
+    return {
+        steps: primitives.map((primitive)=>({
+                stepId: primitive.stepId,
+                label: primitive.label ?? primitive.stepId,
+                character: characterOf(primitive),
+                after: primitive.after ?? []
+            }))
+    };
+}
+/**
+ * Aggregation priority when a curated group clusters several runtime steps
+ * with different characters — the strongest signal wins so a group never
+ * under-represents itself (a group containing one human `await` step reads
+ * as `await` even if every other step in it is `deterministic`).
+ */ const CHARACTER_PRIORITY = [
+    "await",
+    "gate",
+    "child",
+    "action",
+    "reasoning",
+    "sleep",
+    "deterministic",
+    "other"
+];
+function aggregateCharacter(characters) {
+    for (const candidate of CHARACTER_PRIORITY){
+        if (characters.includes(candidate)) return candidate;
+    }
+    return "other";
+}
+/**
+ * Curates a derived `DisplayFlow` into an author's declared groups. Every
+ * group's `steps` is validated against the flow's actual step ids — an
+ * unknown id throws immediately rather than silently producing an empty or
+ * partial group.
+ */ export function applyDisplayOverlay(flow, overlay) {
+    const byId = new Map(flow.steps.map((step)=>[
+            step.stepId,
+            step
+        ]));
+    const groups = overlay.groups.map((group)=>{
+        const characters = [];
+        for (const stepId of group.steps){
+            const step = byId.get(stepId);
+            if (step === undefined) {
+                throw new Error(`display overlay group ${JSON.stringify(group.key)} references unknown step ${JSON.stringify(stepId)}`);
+            }
+            characters.push(step.character);
+        }
+        return {
+            key: group.key,
+            label: group.label,
+            character: aggregateCharacter(characters),
+            stepIds: group.steps,
+            ...group.activityLabel !== undefined ? {
+                activityLabel: group.activityLabel
+            } : {}
+        };
+    });
+    return {
+        groups
+    };
+}
+/**
+ * Maps pure display-flow steps into `StepList` items, all `pending` unless a
+ * status lookup is given — the host overlays real run state on top once it
+ * has any.
+ */ export function stepListFromDisplayFlow(steps, statusById) {
+    const lookup = statusById instanceof Map ? (id)=>statusById.get(id) : statusById !== undefined ? (id)=>statusById[id] : ()=>undefined;
+    return steps.map((step)=>({
+            id: step.stepId,
+            name: step.label,
+            status: lookup(step.stepId) ?? "pending",
+            character: step.character
+        }));
+}

package/dist/lib/workflow-registry.d.ts

@@ -0,0 +1,90 @@
+import type { BadgeTone } from "../ui/badge.js";
+import type { StatusDotTone } from "../ui/status-dot.js";
+import type { DisplayStepCharacter } from "./workflow-display-flow.js";
+/**
+ * Shapes for the unified workflows registry surface: a combined list of live
+ * runs and schedules, plus the inspector and picker that sit next to it.
+ *
+ * `WorkflowScope` and `WorkflowStatusTone` are a coarser vocabulary than
+ * `RunStatus` in `workflow-run.ts` — that module models one run's lifecycle
+ * (`provisioning` through `stopped`) for the active-runs dock; this module
+ * models the tone a *list row or inspector chip* renders, which collapses a
+ * schedule's paused/active state and a run's phase onto the same five tones.
+ * They are deliberately not merged: a dock strip and a combined registry list
+ * answer different questions about the same underlying runs.
+ */
+export type WorkflowScope = "personal" | "tenant";
+export type WorkflowStatusTone = "running" | "awaiting" | "done" | "paused" | "fail";
+export declare const WORKFLOW_STATUS_LABEL: Record<WorkflowStatusTone, string>;
+/** Badge tone for a status chip composed as `<Badge tone={...}><StatusDot .../>{label}</Badge>`. */
+export declare const WORKFLOW_STATUS_BADGE_TONE: Record<WorkflowStatusTone, BadgeTone>;
+/** Dot tone for the same chip — see `status-dot.tsx` for why only three exist. */
+export declare const WORKFLOW_STATUS_DOT_TONE: Record<WorkflowStatusTone, StatusDotTone>;
+/** Whether a status tone's dot pulses by default — the two tones that are
+ * still moving or still waiting on someone. A caller composing `Badge` +
+ * `StatusDot` directly (there is no `StatusChip` component) passes this as
+ * `StatusDot`'s `live` prop unless it has a more specific signal. */
+export declare function workflowStatusLive(tone: WorkflowStatusTone): boolean;
+export declare function workflowScopeLabel(scope: WorkflowScope): string;
+/** Badge tone for a workflow's scope. `tenant` gets the info tone so it reads
+ * as shared infrastructure; `personal` gets the accent tone that marks
+ * "yours" everywhere else in the registry. */
+export declare const WORKFLOW_SCOPE_BADGE_TONE: Record<WorkflowScope, BadgeTone>;
+/** A live run's phase as an inspector or list row reports it — a coarser
+ * vocabulary than `RunStatus` in `workflow-run.ts` (no `provisioning`), for
+ * surfaces that only distinguish what a reader can act on. */
+export type LiveRunPhase = "running" | "awaiting" | "completed" | "failed" | "cancelled";
+export declare const LIVE_RUN_PHASE_TONE: Record<LiveRunPhase, WorkflowStatusTone>;
+export declare const LIVE_RUN_PHASE_LABEL: Record<LiveRunPhase, string>;
+export type WorkflowListItemKind = "run" | "schedule";
+/** One dense row in the combined live-runs-and-schedules list. */
+export type WorkflowListItem = {
+    readonly id: string;
+    readonly itemKind: WorkflowListItemKind;
+    /** Primary label — the workflow's kind, already humanised. */
+    readonly title: string;
+    /** Secondary line under the title: an alias, an origin tag. */
+    readonly subtitle?: string;
+    /** The "when" column: origin phrase for a run, cadence for a schedule. */
+    readonly when: string;
+    readonly scope: WorkflowScope;
+    readonly statusTone: WorkflowStatusTone;
+    readonly statusLabel: string;
+    /** Next-fire or elapsed text, already formatted by the caller. */
+    readonly nextOrElapsed: string;
+    /** Highlights `nextOrElapsed` — the next fire is close, or the run is fresh. */
+    readonly nextSoon?: boolean;
+    /** A live run parked on a human decision gets a subtle accent stripe. */
+    readonly needsYou?: boolean;
+};
+export type GateKind = "reviewList" | "choice" | "form" | "multiSelect";
+export declare const GATE_KIND_LABEL: Record<GateKind, string>;
+/** Shell model for a pending gate; the interactive payload is the caller's. */
+export type GateShellModel = {
+    readonly kind: GateKind;
+    readonly title: string;
+    readonly prompt?: string;
+};
+/** One offering in a workflow-kind picker (distinct from `WorkflowOffering` in
+ * `workflow-catalog.tsx`, which drives the run-once grid): this shape adds
+ * category grouping and an "already on" badge for a picker that lists kinds
+ * to attach to a schedule or an automation rather than to run once. */
+export type KindPickerItem = {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    /** Grouping key. Omit when every item shares one category. */
+    readonly category?: string;
+    readonly categoryLabel?: string;
+    readonly alreadyOn?: boolean;
+    readonly alreadyOnLabel?: string;
+};
+export type StepDisplayStatus = "pending" | "active" | "done" | "failed";
+/** One step row in the live inspector's step list. */
+export type StepListItem = {
+    readonly id: string;
+    readonly name: string;
+    readonly status: StepDisplayStatus;
+    readonly meta?: string;
+    readonly character?: DisplayStepCharacter;
+};

package/dist/lib/workflow-registry.js

@@ -0,0 +1,56 @@
+export const WORKFLOW_STATUS_LABEL = {
+    running: "Running",
+    awaiting: "Needs you",
+    done: "Done",
+    paused: "Paused",
+    fail: "Failed"
+};
+/** Badge tone for a status chip composed as `<Badge tone={...}><StatusDot .../>{label}</Badge>`. */ export const WORKFLOW_STATUS_BADGE_TONE = {
+    running: "info",
+    awaiting: "accent",
+    done: "success",
+    paused: "neutral",
+    fail: "danger"
+};
+/** Dot tone for the same chip — see `status-dot.tsx` for why only three exist. */ export const WORKFLOW_STATUS_DOT_TONE = {
+    running: "emphasis",
+    awaiting: "emphasis",
+    done: "neutral",
+    paused: "neutral",
+    fail: "danger"
+};
+/** Whether a status tone's dot pulses by default — the two tones that are
+ * still moving or still waiting on someone. A caller composing `Badge` +
+ * `StatusDot` directly (there is no `StatusChip` component) passes this as
+ * `StatusDot`'s `live` prop unless it has a more specific signal. */ export function workflowStatusLive(tone) {
+    return tone === "running" || tone === "awaiting";
+}
+export function workflowScopeLabel(scope) {
+    return scope === "tenant" ? "Everyone" : "Just me";
+}
+/** Badge tone for a workflow's scope. `tenant` gets the info tone so it reads
+ * as shared infrastructure; `personal` gets the accent tone that marks
+ * "yours" everywhere else in the registry. */ export const WORKFLOW_SCOPE_BADGE_TONE = {
+    tenant: "info",
+    personal: "accent"
+};
+export const LIVE_RUN_PHASE_TONE = {
+    running: "running",
+    awaiting: "awaiting",
+    completed: "done",
+    failed: "fail",
+    cancelled: "fail"
+};
+export const LIVE_RUN_PHASE_LABEL = {
+    running: "Running",
+    awaiting: "Needs you",
+    completed: "Done",
+    failed: "Failed",
+    cancelled: "Cancelled"
+};
+export const GATE_KIND_LABEL = {
+    reviewList: "Needs you · review",
+    choice: "Needs you · choice",
+    form: "Needs you · form",
+    multiSelect: "Needs you · select"
+};

package/dist/lib/workflow-run-error.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Classification/sanitization boundary for a failed step's raw error text.
+ *
+ * A step's own thrown error can carry internal identifiers, stack fragments
+ * or internal hostnames, and nothing user-facing may render it as-is.
+ * `classifyRunError` maps the known-safe shapes — a `"<Provider> API error:
+ * <status> …"` tool-package convention, a network-level failure — to
+ * plain-language messages, and defaults everything unrecognized to a
+ * generic-but-honest internal message. The raw text survives on the result
+ * for an operator surface or a log; it must never reach an end-user panel.
+ */
+export type RunErrorKind = "external-auth" | "external-rate-limit" | "external-unavailable" | "external-rejected" | "network" | "internal";
+export type ClassifiedRunError = {
+    readonly kind: RunErrorKind;
+    /** Plain-language message safe to render to end users. */
+    readonly userMessage: string;
+    /** The original error text — operator surfaces and logs only. */
+    readonly raw: string;
+};
+export declare function classifyRunError(raw: string): ClassifiedRunError;
+/**
+ * Plain-language line for a step's live inference issue — a still-running
+ * step reporting itself as stalled-but-alive rather than dead. The input is
+ * whatever fixed category enum the host's runtime already classifies
+ * inference failures into (a timeout, a quota hit, a bad credential), passed
+ * through as a plain string so this module carries no dependency on the
+ * runtime's error types. The step keeps running for every category except
+ * `context_overflow`, where the input itself must shrink before a retry can
+ * help — its message is the one that omits the retry claim.
+ */
+export declare function describeLiveInferenceIssue(category: string): string;

package/dist/lib/workflow-run-error.js

@@ -0,0 +1,105 @@
+/**
+ * Classification/sanitization boundary for a failed step's raw error text.
+ *
+ * A step's own thrown error can carry internal identifiers, stack fragments
+ * or internal hostnames, and nothing user-facing may render it as-is.
+ * `classifyRunError` maps the known-safe shapes — a `"<Provider> API error:
+ * <status> …"` tool-package convention, a network-level failure — to
+ * plain-language messages, and defaults everything unrecognized to a
+ * generic-but-honest internal message. The raw text survives on the result
+ * for an operator surface or a log; it must never reach an end-user panel.
+ */ const PROVIDER_API_ERROR = /^([A-Za-z][A-Za-z0-9]*(?: [A-Za-z0-9]+){0,2}) API error: (\d{3})/;
+const ANY_API_ERROR = /\bAPI error: (\d{3})/;
+const GENERIC_PROVIDER_LABEL = "An external service";
+const NETWORK_PATTERNS = [
+    /\bfetch failed\b/i,
+    /\bECONN(REFUSED|RESET|ABORTED)\b/,
+    /\bENOTFOUND\b/,
+    /\bETIMEDOUT\b/,
+    /\bEAI_AGAIN\b/,
+    /\bsocket\b.*\b(closed|hang ?up|reset)\b/i,
+    /\b(request|fetch|connect(?:ion)?|socket)\b.*\btimed out\b/i,
+    /\bnetwork (error|request failed)\b/i
+];
+const INTERNAL_MESSAGE = "Something went wrong inside this workflow run. Try running it again; if it keeps failing, contact your workspace admin.";
+const NETWORK_MESSAGE = "A service this workflow depends on couldn't be reached. Try running it again in a moment.";
+function classifyProviderError(provider, status, raw) {
+    const credentialRef = provider === GENERIC_PROVIDER_LABEL ? "credential's" : `${provider} credential's`;
+    if (status === 401 || status === 403) {
+        return {
+            kind: "external-auth",
+            userMessage: `${provider} declined the request (${status}). Check the connected ${credentialRef} access and try again.`,
+            raw
+        };
+    }
+    if (status === 429) {
+        return {
+            kind: "external-rate-limit",
+            userMessage: `${provider} is rate-limiting requests right now. Wait a few minutes and run this again.`,
+            raw
+        };
+    }
+    if (status >= 500) {
+        return {
+            kind: "external-unavailable",
+            userMessage: `${provider} had a problem on its end (${status}). Try running this again shortly.`,
+            raw
+        };
+    }
+    return {
+        kind: "external-rejected",
+        userMessage: `${provider} rejected the request (${status}). Try again, and contact your workspace admin if it keeps failing.`,
+        raw
+    };
+}
+export function classifyRunError(raw) {
+    const providerMatch = PROVIDER_API_ERROR.exec(raw);
+    if (providerMatch?.[1] !== undefined && providerMatch[2] !== undefined) {
+        return classifyProviderError(providerMatch[1], Number(providerMatch[2]), raw);
+    }
+    const anyApiErrorMatch = ANY_API_ERROR.exec(raw);
+    if (anyApiErrorMatch?.[1] !== undefined) {
+        return classifyProviderError(GENERIC_PROVIDER_LABEL, Number(anyApiErrorMatch[1]), raw);
+    }
+    if (NETWORK_PATTERNS.some((pattern)=>pattern.test(raw))) {
+        return {
+            kind: "network",
+            userMessage: NETWORK_MESSAGE,
+            raw
+        };
+    }
+    return {
+        kind: "internal",
+        userMessage: INTERNAL_MESSAGE,
+        raw
+    };
+}
+/**
+ * Plain-language line for a step's live inference issue — a still-running
+ * step reporting itself as stalled-but-alive rather than dead. The input is
+ * whatever fixed category enum the host's runtime already classifies
+ * inference failures into (a timeout, a quota hit, a bad credential), passed
+ * through as a plain string so this module carries no dependency on the
+ * runtime's error types. The step keeps running for every category except
+ * `context_overflow`, where the input itself must shrink before a retry can
+ * help — its message is the one that omits the retry claim.
+ */ export function describeLiveInferenceIssue(category) {
+    switch(category){
+        case "timeout":
+            return "Model provider timed out — retrying";
+        case "retryable":
+            return "Model provider had a transient error — retrying";
+        case "quota_exhausted":
+            return "Model provider is rate-limiting requests — retrying";
+        case "credential_failure":
+            return "Model provider rejected the credential — retrying";
+        case "context_overflow":
+            return "Input is too large for the model";
+        case "protocol_mismatch":
+            return "Model provider returned an unexpected response — retrying";
+        case "aborted":
+            return "The step was interrupted — retrying";
+        default:
+            return "Model provider had a problem — retrying";
+    }
+}

package/dist/lib/workflow-run-progress.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared run-progress reasoning for a stepper or sidebar rendering a
+ * workflow's live progress.
+ *
+ * `RunProgress` is a plain, generic snapshot — a phase and a step-id-to-phase
+ * map — rather than the host's own run-state type. A step is only marked
+ * `"completed"` once the host's runtime actually resolves its output, and
+ * that resolution can lag behind a gate's own phase (an `awaiting-signal`
+ * step's completion event can be missing from a projection for a beat), so a
+ * gate's own phase is not a reliable "done" signal on its own. The robust
+ * rule encoded here: a step counts as passed once its own phase is completed
+ * OR any later step has progressed at all.
+ */
+export type StepPhase = "pending" | "in-flight" | "awaiting-signal" | "awaiting-timer" | "completed" | "failed";
+export type RunPhase = "pending" | "in-flight" | "completed" | "failed";
+export type RunStepSnapshot = {
+    readonly phase: StepPhase;
+    /** Sanitizable raw error text — pass through `classifyRunError` before display. */
+    readonly lastErrorMessage?: string;
+};
+export type RunProgress = {
+    readonly phase: RunPhase;
+    readonly steps: ReadonlyMap<string, RunStepSnapshot>;
+};
+export type WorkflowStepStatus = "completed" | "current" | "pending" | "failed";
+/** A single step descriptor for a stepper or sidebar. */
+export type WorkflowStep = {
+    readonly number: number;
+    readonly label: string;
+    readonly status: WorkflowStepStatus;
+};
+/** Label colour for a step's status, shared by every stepper/sidebar rendering. */
+export declare function workflowStepLabelClass(status: WorkflowStepStatus): string;
+/** Mark glyph for a step's status: a checkmark, an exclamation, or its number. */
+export declare function workflowStepGlyph(status: WorkflowStepStatus, number: number): string;
+/**
+ * A stepper entry backed by one or more runtime step ids, in run order. A
+ * linear workflow maps one runtime id per display step; a clustered one
+ * (a multi-source research phase, say) groups several. The group's *last* id
+ * is its terminal step — the group only reads `completed` once that one does.
+ */
+export type DisplayStep = {
+    readonly key: string;
+    readonly label: string;
+    readonly stepIds: readonly string[];
+    /** Present-progress verb shown on a live status line while this step is
+     * in-flight (e.g. "Saving to workbench"). Omit for a human gate or an
+     * intake step — an unlabeled active step shows no line rather than
+     * inventing one. */
+    readonly activityLabel?: string;
+};
+export declare function getStepPhase(progress: RunProgress | null, stepId: string): StepPhase | undefined;
+export declare function isStepRunning(phase: StepPhase | undefined): boolean;
+/** The aggregate phase of a display step from its runtime steps. */
+export declare function displayStepPhase(progress: RunProgress | null, stepIds: readonly string[]): StepPhase | undefined;
+/**
+ * Index of the display step the run is currently on. A step whose own phase
+ * is `failed` is never treated as passed even when a later, independently
+ * running branch has progressed — independent steps can run concurrently, so
+ * a later step's progress says nothing about whether this one failed.
+ * Returns the last index once every step is complete.
+ */
+export declare function activeDisplayStepIndex(progress: RunProgress | null, steps: readonly DisplayStep[]): number;
+export declare function buildStepperSteps(progress: RunProgress | null, steps: readonly DisplayStep[]): WorkflowStep[];
+/** The active display step, or `null` while the run is terminal. */
+export declare function activeDisplayStep(progress: RunProgress | null, steps: readonly DisplayStep[]): DisplayStep | null;
+/**
+ * The "what's happening now" verb for a live status line, taken from the
+ * active step's `activityLabel`. Returns `null` — showing no line — once the
+ * run is terminal, while the first step owns its own loading UI, once the
+ * active group is done or parked on a human gate, or when the active step
+ * carries no `activityLabel` at all (a gate or intake step): silence there is
+ * correct, never a stepper noun standing in for it.
+ */
+export declare function liveStatusLabel(progress: RunProgress | null, steps: readonly DisplayStep[]): string | null;
+/** Label of the first display step whose aggregate phase is `failed`. Does
+ * not require `progress.phase === "failed"` — a caller flagging failure from
+ * a single failed step ahead of the run's own phase flip still gets a name. */
+export declare function failedDisplayStepLabel(progress: RunProgress | null, steps: readonly DisplayStep[]): string | null;
+/** The sanitized end-user message from whichever step failed the run, or
+ * `null` if the run has not failed or no step carries an error. Uses the
+ * first error found in map-iteration order — a run design that attaches an
+ * error to more than one step at once is a design this cannot disambiguate. */
+export declare function failedRunErrorMessage(progress: RunProgress | null): string | null;
+/**
+ * True only for a genuine never-started run: a non-null progress with an
+ * empty step map, where that emptiness came from an event log that was
+ * actually read. `logRead` distinguishes that from a log-unavailable fallback
+ * (a legacy run, or a read error) that can synthesize the same empty-step
+ * shape regardless of phase — in that case whether it started is unknown, so
+ * this returns `false` rather than making a false "never started" claim.
+ */
+export declare function runNeverStarted(progress: RunProgress | null, logRead: boolean): boolean;
+/** Honest copy for the pre-interactive window before a run's first step has
+ * recorded any activity: queued (`pending`, or no progress yet) reads
+ * differently from a runtime already booting that first step. */
+export declare function runStartLabel(progress: RunProgress | null): string;