@llm4ts/runner 2.19.0 → 2.20.0

package/dist/AgentTree.d.ts

@@ -0,0 +1,150 @@
+import { FlowEvent } from "@llm4ts/flow/FlowEvents";
+import type { TraceLine } from "@llm4ts/flow/FlowRecorder";
+/**
+ * The agent tree (ADR 0022): a full-screen view of a running or finished
+ * flow — the orchestrator, the judgment layer, the story lanes on the
+ * executor roster, the judge seat and a session log.
+ *
+ * Pure: `reduceTree` folds what a run published into a `TreeState`, and
+ * `renderTree` draws that state at a width. Where the inputs come from (the
+ * event hub of a live run, or a trace file) is the host's business, so a live
+ * view, a finished run and a replay are the same fold.
+ */
+export type TreeInput = {
+    readonly _tag: "Event";
+    readonly at: number;
+    readonly event: FlowEvent;
+} | {
+    readonly _tag: "RunEnded";
+    readonly at: number;
+    readonly outcome: string;
+};
+export type LaneStatus = "running" | "done" | "failed";
+export interface TreeLane {
+    readonly id: string;
+    /** The lane's open stages below `story <id>`, innermost last. */
+    readonly stages: ReadonlyArray<string>;
+    readonly executor: string | undefined;
+    readonly startedAt: number;
+    readonly status: LaneStatus;
+    readonly lastTool: string | undefined;
+    /** The lane's most recent tool calls, oldest first, for the expanded view. */
+    readonly tools: ReadonlyArray<string>;
+    readonly tokens: number;
+    readonly costUsd: number;
+}
+export type LogSource = "lane" | "run" | "roster" | "judge";
+export interface TreeLogEntry {
+    readonly at: number;
+    readonly source: LogSource;
+    /** The lane, executor or `flow` the entry is about. */
+    readonly who: string;
+    readonly what: string;
+}
+/** A story as the epic's board lists it, before or without a lane of its own. */
+export interface TreeStory {
+    readonly id: string;
+    readonly status: "planned" | "active" | "waiting" | "done" | "failed" | "skipped";
+}
+/** A lease an executor holds now: its role and who it is for (a story id). */
+export interface TreeLease {
+    readonly executor: string;
+    readonly role: string;
+    readonly label: string | undefined;
+}
+/** The judge seat: who sits in it, and how often it was asked. */
+export interface TreeJudge {
+    readonly executor: string | undefined;
+    readonly reviews: number;
+    readonly verdicts: number;
+}
+/** The latest story verdict (`StoryJudged`). */
+export interface TreeVerdict {
+    readonly lane: string;
+    readonly round: number;
+    readonly cleared: boolean;
+    readonly issues: number;
+    readonly dimensions: ReadonlyArray<{
+        readonly id: string;
+        readonly score: number;
+        readonly max: number;
+    }>;
+}
+/** The latest typed judgment per key (`JudgmentObserved`). */
+export interface TreeJudgment {
+    readonly key: string;
+    readonly certainty: number;
+    readonly decision: string;
+}
+export interface TreeState {
+    readonly title: string;
+    readonly action: string | undefined;
+    /** The board's stories, in plan order; lanes not on it are added after. */
+    readonly stories: ReadonlyArray<TreeStory>;
+    readonly startedAt: number | undefined;
+    readonly now: number | undefined;
+    /** Run-wide open stages, innermost last. */
+    readonly stages: ReadonlyArray<string>;
+    /** Lanes in the order they started. */
+    readonly lanes: ReadonlyArray<TreeLane>;
+    /** Executors in the order the run first named them. */
+    readonly executors: ReadonlyArray<string>;
+    readonly leases: ReadonlyArray<TreeLease>;
+    /** Executors out of the round, with the roster's reason. */
+    readonly exclusions: ReadonlyArray<{
+        readonly executor: string;
+        readonly reason: string;
+    }>;
+    readonly judge: TreeJudge;
+    readonly verdict: TreeVerdict | undefined;
+    readonly judgments: ReadonlyArray<TreeJudgment>;
+    readonly log: ReadonlyArray<TreeLogEntry>;
+    readonly tokens: number;
+    /** Estimated: the backend's own figure when it reports one, else the price list. */
+    readonly costUsd: number;
+    /** The run's outcome once its trace says it ended; a live run has none. */
+    readonly ended: string | undefined;
+}
+export interface TreeOptions {
+    readonly title?: string;
+    /** What the run set out to do ("run plan", "round 2"), when the caller knows. */
+    readonly action?: string;
+    readonly stories?: ReadonlyArray<TreeStory>;
+}
+export declare const emptyTree: (options?: TreeOptions) => TreeState;
+export declare const reduceTree: (state: TreeState, input: TreeInput) => TreeState;
+/**
+ * A trace's lines as tree inputs. Kinds this version does not know — raw
+ * stream lines, events from a newer llm4ts — are skipped, so any trace renders.
+ */
+export declare const treeInputsOfTrace: (lines: ReadonlyArray<TraceLine>) => ReadonlyArray<TreeInput>;
+export type TreeMode = "lanes" | "executors";
+/** What the reader chose to look at; the run's state is separate. */
+export interface TreeView {
+    readonly mode: TreeMode;
+    /** The selected lane's story id. */
+    readonly selected: string | undefined;
+    readonly expanded: boolean;
+    readonly fullLog: boolean;
+}
+export declare const initialView: TreeView;
+/**
+ * The view after a key: arrows or 1–9 select a running lane, enter expands
+ * it, escape collapses, `e` switches lanes and executors, `l` the full log,
+ * `q` quits. Keys it does not know return the same view.
+ */
+export declare const onTreeKey: (view: TreeView, key: string, state: TreeState) => TreeView | "quit";
+export interface TreeRenderOptions {
+    readonly width: number;
+    readonly colour: boolean;
+    readonly view: TreeView;
+    /** The terminal's rows; the frame fits them (see `renderTree`). */
+    readonly height?: number;
+}
+/**
+ * The tree at a width and, when `height` is given, no taller: the session
+ * log gives way first — fewer lines, down to one, then none — and only then
+ * is the frame cut, keeping its status lines, so a redraw never scrolls.
+ */
+export declare const renderTree: (state: TreeState, options: TreeRenderOptions) => ReadonlyArray<string>;
+//# sourceMappingURL=AgentTree.d.ts.map

package/dist/AgentTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTree.d.ts","sourceRoot":"","sources":["../src/AgentTree.ts"],"names":[],"mappings":"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"}