@llm4ts/runner 2.21.0 → 2.22.0

package/src/Watch.ts

@@ -1,5 +1,6 @@
 import { readdirSync, existsSync, statSync } from "node:fs"
 import { join } from "node:path"
+import * as Clock from "effect/Clock"
 import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Queue from "effect/Queue"
@@ -22,7 +23,7 @@ import {
   type TreeState,
   type TreeView
 } from "./AgentTree.ts"
-import { nodeTreeKeys } from "./AgentTreeSurface.ts"
+import { enterScreen, leaveScreen, makeScreenPainter, nodeTreeKeys } from "./AgentTreeSurface.ts"
 import { nodeListTraces, TraceDirectoryName } from "./Costs.ts"
 import { nodePlainFileStore } from "./NodePlainFileStore.ts"
 
@@ -42,6 +43,8 @@ export interface WatchOptions {
   readonly replay?: boolean
   /** Replay speed-up (default 10). */
   readonly speed?: number
+  /** A live lane with no event for this long is marked idle (`LLM4TS_IDLE_AFTER`). */
+  readonly idleAfterMs?: number
 }
 
 export interface WatchOutput {
@@ -68,7 +71,13 @@ export class WatchTargetMissing extends Schema.TaggedError<WatchTargetMissing>()
   { message: Schema.String }
 ) {}
 
-interface WatchTarget {
+/** Where a run's trace and its epic are read from. */
+export type TraceSources = Pick<WatchDependencies, "files" | "listTraces" | "listEpics">
+
+/** A trace to read: given, an epic's latest run, or the newest in the repository. */
+export type TraceChoice = Pick<WatchOptions, "repo" | "trace" | "epic">
+
+export interface WatchTarget {
   readonly tracePath: string
   readonly epicDir: string | undefined
   readonly run: EpicRun | undefined
@@ -80,7 +89,7 @@ const epicsDirOf = (repo: string): string => join(repo, TraceDirectoryName, "epi
 const epicOfTrace = (
   tracePath: string,
   repo: string,
-  dependencies: WatchDependencies
+  dependencies: TraceSources
 ): Effect.Effect<{ readonly dir: string; readonly run: EpicRun } | undefined, FlowError> =>
   Effect.gen(function* () {
     const epicsDir = epicsDirOf(repo)
@@ -96,9 +105,9 @@ const epicOfTrace = (
     return undefined
   })
 
-const resolveTarget = (
-  options: WatchOptions,
-  dependencies: WatchDependencies
+export const resolveTraceTarget = (
+  options: TraceChoice,
+  dependencies: TraceSources
 ): Effect.Effect<WatchTarget, FlowError | WatchTargetMissing> =>
   Effect.gen(function* () {
     if (options.epic !== undefined) {
@@ -143,12 +152,14 @@ const actionWords = (run: EpicRun | undefined): string | undefined => {
 /** The tree before any event: the epic's board, when the trace belongs to one. */
 const startingTree = (
   target: WatchTarget,
-  files: PlainFileStoreShape
+  files: PlainFileStoreShape,
+  idleAfterMs: number | undefined
 ): Effect.Effect<TreeState, FlowError> =>
   Effect.gen(function* () {
     const action = actionWords(target.run)
+    const idle = idleAfterMs === undefined ? {} : { idleAfterMs }
     if (target.epicDir === undefined) {
-      return emptyTree(action === undefined ? {} : { action })
+      return emptyTree({ ...idle, ...(action === undefined ? {} : { action }) })
     }
     const boardDir =
       target.run?.round === undefined
@@ -159,6 +170,7 @@ const startingTree = (
     return emptyTree({
       title: board === undefined ? `epic ${epicId}` : board.title.replace(/^Epic:\s*/u, "epic "),
       stories: (board?.items ?? []).map((item) => ({ id: item.id, status: item.status })),
+      ...idle,
       ...(action === undefined ? {} : { action })
     })
   })
@@ -169,9 +181,6 @@ const readInputs = (
 ): Effect.Effect<ReadonlyArray<TreeInput>, FlowError> =>
   Effect.map(readTrace(files, target.tracePath), treeInputsOfTrace)
 
-const enterScreen = "\u001b[?1049h\u001b[?25l"
-const leaveScreen = "\u001b[?25h\u001b[?1049l"
-const home = "\u001b[H\u001b[2J"
 const pollInterval = Duration.millis(500)
 const replayGapCap = 2_000
 
@@ -184,17 +193,22 @@ const draw = (state: TreeState, view: TreeView, output: WatchOutput, height?: nu
   }).join("\n")
 
 /** A full-screen frame: no taller than the terminal. */
-const drawScreen = (state: TreeState, view: TreeView, output: WatchOutput): string =>
-  draw(state, view, output, output.rows())
+const screenLines = (
+  state: TreeState,
+  view: TreeView,
+  output: WatchOutput
+): ReadonlyArray<string> => draw(state, view, output, output.rows()).split("\n")
 
 export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function* (
   options: WatchOptions,
   dependencies: WatchDependencies
 ): Effect.fn.Return<void, FlowError | WatchTargetMissing> {
-  const target = yield* resolveTarget(options, dependencies)
+  const target = yield* resolveTraceTarget(options, dependencies)
   const { files, output } = dependencies
   const fold = (inputs: ReadonlyArray<TreeInput>): Effect.Effect<TreeState, FlowError> =>
-    Effect.map(startingTree(target, files), (start) => inputs.reduce(reduceTree, start))
+    Effect.map(startingTree(target, files, options.idleAfterMs), (start) =>
+      inputs.reduce(reduceTree, start)
+    )
 
   if (!output.interactive) {
     const state = yield* Effect.flatMap(readInputs(target, files), fold)
@@ -236,13 +250,26 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
           Effect.as(Effect.sleep(wait), false)
         )
 
+      const painter = yield* makeScreenPainter
       yield* output.write(enterScreen)
       yield* Effect.gen(function* () {
         while (true) {
           const current = yield* Ref.get(inputs)
           const count = yield* Ref.get(shown)
-          const state = yield* fold(current.slice(0, count))
-          yield* output.write(`${home}${drawScreen(state, yield* Ref.get(view), output)}`)
+          const folded = yield* fold(current.slice(0, count))
+          // Following a live run, the clock moves between events; a replay
+          // and a finished run keep the trace's own time.
+          const state =
+            options.replay !== true && folded.ended === undefined
+              ? reduceTree(folded, { _tag: "Tick", at: yield* Clock.currentTimeMillis })
+              : folded
+          const text = yield* painter.paint(
+            screenLines(state, yield* Ref.get(view), output),
+            `${output.columns()}x${output.rows()}`
+          )
+          if (text.length > 0) {
+            yield* output.write(text)
+          }
           const replaying = options.replay === true && count < current.length
           const gap = replaying
             ? Math.min(replayGapCap, (current[count]?.at ?? 0) - (current[count - 1]?.at ?? 0)) /
@@ -271,6 +298,12 @@ const nodeListEpics = (directory: string): ReadonlyArray<string> =>
     ? readdirSync(directory).filter((name) => statSync(join(directory, name)).isDirectory())
     : []
 
+export const nodeTraceSources: TraceSources = {
+  files: nodePlainFileStore,
+  listTraces: nodeListTraces,
+  listEpics: nodeListEpics
+}
+
 export const nodeWatchDependencies = (
   environment: Readonly<Record<string, string | undefined>> = process.env
 ): WatchDependencies => {