@llm4ts/runner 2.23.0 → 2.24.0

package/src/Transcripts.ts

@@ -0,0 +1,274 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { summariseToolArgs } from "@llm4ts/flow/Activity"
+import { TranscriptEntry, type TranscriptSink } from "@llm4ts/flow/Transcript"
+import { duration } from "./AgentTree.ts"
+
+/**
+ * Transcripts on disk (`llm4ts run --transcript`): one JSON line per entry,
+ * one file per story (`<lane>.jsonl`) and `run.jsonl` for the rest, under
+ * `.llm4ts/transcripts/<run-id>/`. They hold the customer's code and the
+ * model's replies, so only their owner can read them, and a write that fails
+ * never fails the run.
+ */
+
+/** `LLM4TS_TRANSCRIPT=on` (what `--transcript` sets); also `1`, `true`, `yes`. */
+export const transcriptsWanted = (
+  environment: Readonly<Record<string, string | undefined>>
+): boolean => /^(on|1|true|yes)$/iu.test(environment.LLM4TS_TRANSCRIPT?.trim() ?? "")
+
+export const transcriptFileOf = (lane: string | undefined): string =>
+  `${(lane ?? "run").replace(/[^A-Za-z0-9._-]/gu, "_")}.jsonl`
+
+const encode = Schema.encodeSync(Schema.fromJsonString(TranscriptEntry))
+
+export const nodeTranscriptSink = (directory: string): TranscriptSink => {
+  let made = false
+  return {
+    write: (lane, entry) =>
+      Effect.sync(() => {
+        try {
+          if (!made) {
+            mkdirSync(directory, { recursive: true, mode: 0o700 })
+            made = true
+          }
+          appendFileSync(join(directory, transcriptFileOf(lane)), `${encode(entry)}\n`, {
+            mode: 0o600
+          })
+        } catch {
+          // A transcript is a window on the run, never a reason to stop it.
+        }
+      })
+  }
+}
+
+// ── reading ─────────────────────────────────────────────────────────────────
+
+export interface TranscriptView {
+  readonly width: number
+  /** Only calls made in this role (coder, reviewer, judge, …). */
+  readonly role?: string
+  /** Only calls served by this executor. */
+  readonly executor?: string
+  /** Keep the last lines only. */
+  readonly last?: number
+  /** Where the clock in the headers starts; the first entry's time by default. */
+  readonly since?: number
+}
+
+const clockOf = (ms: number): string => {
+  const seconds = Math.max(0, Math.floor(ms / 1_000))
+  return [Math.floor(seconds / 3_600), Math.floor(seconds / 60) % 60, seconds % 60]
+    .map((part) => String(part).padStart(2, "0"))
+    .join(":")
+}
+
+const cut = (line: string, width: number): string =>
+  [...line].length <= width ? line : `${[...line].slice(0, Math.max(0, width - 1)).join("")}…`
+
+/** `text` as lines of at most `width`, the first after `prefix`, the rest indented. */
+const wrapped = (prefix: string, text: string, width: number, limit = Infinity): Array<string> => {
+  const room = Math.max(10, width - prefix.length)
+  const lines: Array<string> = []
+  for (const paragraph of text.split("\n")) {
+    let line = ""
+    for (const word of paragraph.split(/\s+/u).filter((part) => part.length > 0)) {
+      if (line.length > 0 && line.length + 1 + word.length > room) {
+        lines.push(line)
+        line = ""
+      }
+      line = line.length === 0 ? cut(word, room) : `${line} ${word}`
+    }
+    lines.push(line)
+  }
+  const kept = lines.filter((line, index) => line.length > 0 || index < lines.length - 1)
+  const shown = kept.slice(0, limit)
+  const more = kept.length - shown.length
+  return [
+    ...shown.map((line, index) => `${index === 0 ? prefix : " ".repeat(prefix.length)}${line}`),
+    ...(more > 0 ? [`${" ".repeat(prefix.length)}… (${more} more lines)`] : [])
+  ]
+}
+
+const inputLines = 12
+
+/**
+ * A transcript as the tail pane and `watch --tail` show it: each call under
+ * a header (when, who), its input, the reply as one text, every tool with
+ * the gist of its result, and how long the call took.
+ */
+export const renderTranscript = (
+  entries: ReadonlyArray<TranscriptEntry>,
+  view: TranscriptView
+): ReadonlyArray<string> => {
+  const { width } = view
+  const start = view.since ?? entries[0]?.at ?? 0
+  const wanted = new Set(
+    entries.flatMap((entry) =>
+      entry._tag === "Call" &&
+      (view.role === undefined || entry.role === view.role) &&
+      (view.executor === undefined || entry.executor === view.executor)
+        ? [entry.call]
+        : []
+    )
+  )
+  const lines: Array<string> = []
+  let reply: { call: string; text: string } | undefined
+  const flushReply = () => {
+    if (reply !== undefined && reply.text.trim().length > 0) {
+      lines.push(...wrapped("◀ ", reply.text.trim(), width))
+    }
+    reply = undefined
+  }
+  // Only a filter needs the calls' headers; without one every entry shows,
+  // even one passed alone (the tail prints entries as they arrive).
+  const filtering = view.role !== undefined || view.executor !== undefined
+  for (const entry of entries) {
+    if (filtering && !wanted.has(entry.call)) {
+      continue
+    }
+    if (entry._tag !== "Reply") {
+      flushReply()
+    }
+    switch (entry._tag) {
+      case "Call": {
+        const title = `── ${clockOf(entry.at - start)} ${entry.role}${
+          entry.executor === undefined ? "" : ` · ${entry.executor}`
+        } `
+        lines.push(cut(title.padEnd(width, "─"), width))
+        if (entry.system !== undefined) {
+          const [first = "", ...more] = entry.system.split("\n")
+          lines.push(
+            cut(
+              `▶ system: ${first}${more.length === 0 ? "" : ` … (${more.length + 1} lines)`}`,
+              width
+            )
+          )
+        }
+        if (entry.earlier !== undefined && entry.earlier > 0) {
+          lines.push(`▶ (${entry.earlier} earlier messages)`)
+        }
+        lines.push(...wrapped("▶ ", entry.input, width, inputLines))
+        break
+      }
+      case "Reply":
+        reply =
+          reply?.call === entry.call
+            ? { call: entry.call, text: reply.text + entry.text }
+            : { call: entry.call, text: entry.text }
+        break
+      case "Tool":
+        lines.push(cut(`⚙ ${entry.tool} ${summariseToolArgs(entry.args)}`.trimEnd(), width))
+        break
+      case "ToolResult": {
+        const outputLines = entry.output
+          .split("\n")
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0)
+        const gist = outputLines.slice(0, 3).join(" · ")
+        lines.push(
+          cut(
+            `  ↳ ${entry.failed === true ? "failed" : "ok"}${gist.length === 0 ? "" : `: ${gist}`}${
+              outputLines.length > 3 ? " …" : ""
+            }`,
+            width
+          )
+        )
+        break
+      }
+      case "End":
+        lines.push(`  (${duration(entry.ms)}${entry.failed === true ? ", failed" : ""})`)
+        break
+    }
+  }
+  flushReply()
+  return view.last === undefined ? lines : lines.slice(-view.last)
+}
+
+/** How a host reaches a run's transcript files. */
+export interface TranscriptFiles {
+  readonly read: (path: string) => Effect.Effect<string | undefined>
+  /** File names in a directory; none when it does not exist. */
+  readonly list: (directory: string) => ReadonlyArray<string>
+}
+
+const decodeEntry = Schema.decodeUnknownOption(Schema.fromJsonString(TranscriptEntry))
+
+/** A transcript file's entries; a torn last line (a write in progress) is skipped. */
+export const parseTranscript = (text: string): ReadonlyArray<TranscriptEntry> =>
+  text
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      const decoded = decodeEntry(line)
+      return decoded._tag === "Some" ? [decoded.value] : []
+    })
+
+export type TailTarget = { readonly lane: string } | { readonly executor: string }
+
+/**
+ * The entries a tail shows: a story's file, or every file for an executor
+ * (in time order). `undefined` when the run kept no transcript at all.
+ */
+export const loadTranscript = (
+  files: TranscriptFiles,
+  directory: string,
+  target: TailTarget
+): Effect.Effect<ReadonlyArray<TranscriptEntry> | undefined> =>
+  Effect.gen(function* () {
+    const names = files.list(directory).filter((name) => name.endsWith(".jsonl"))
+    if (names.length === 0) {
+      return undefined
+    }
+    const wanted = "lane" in target ? [transcriptFileOf(target.lane)] : names
+    const all: Array<TranscriptEntry> = []
+    for (const name of wanted) {
+      const text = yield* files.read(join(directory, name))
+      all.push(...parseTranscript(text ?? ""))
+    }
+    return "lane" in target ? all : [...all].sort((left, right) => left.at - right.at)
+  })
+
+/**
+ * `rows` lines of a tail, ending `back` lines before its end (scrolled), or
+ * `undefined` when the run has no transcript.
+ */
+export const tailLinesOf = (
+  entries: ReadonlyArray<TranscriptEntry> | undefined,
+  target: TailTarget,
+  role: string | undefined,
+  width: number,
+  rows: number,
+  back = 0
+): ReadonlyArray<string> | undefined => {
+  if (entries === undefined) {
+    return undefined
+  }
+  const lines = renderTranscript(entries, {
+    width,
+    ...(role === undefined ? {} : { role }),
+    ...("executor" in target ? { executor: target.executor } : {})
+  })
+  const end = Math.max(Math.min(rows, lines.length), lines.length - back)
+  return lines.slice(Math.max(0, end - rows), end)
+}
+
+export const nodeTranscriptFiles: TranscriptFiles = {
+  read: (path) =>
+    Effect.sync(() => {
+      try {
+        return readFileSync(path, "utf8")
+      } catch {
+        return undefined
+      }
+    }),
+  list: (directory) => {
+    try {
+      return readdirSync(directory)
+    } catch {
+      return []
+    }
+  }
+}

package/src/Watch.ts

@@ -18,12 +18,22 @@ import {
   onTreeKey,
   reduceTree,
   renderTree,
+  tailTargetOf,
   treeInputsOfTrace,
   type TreeInput,
   type TreeState,
   type TreeView
 } from "./AgentTree.ts"
 import { enterScreen, leaveScreen, makeScreenPainter, nodeTreeKeys } from "./AgentTreeSurface.ts"
+import {
+  loadTranscript,
+  nodeTranscriptFiles,
+  renderTranscript,
+  tailLinesOf,
+  transcriptFileOf,
+  type TailTarget,
+  type TranscriptFiles
+} from "./Transcripts.ts"
 import { nodeListTraces, TraceDirectoryName } from "./Costs.ts"
 import { nodePlainFileStore } from "./NodePlainFileStore.ts"
 
@@ -45,6 +55,8 @@ export interface WatchOptions {
   readonly speed?: number
   /** A live lane with no event for this long is marked idle (`LLM4TS_IDLE_AFTER`). */
   readonly idleAfterMs?: number
+  /** Print this story's or executor's transcript as it grows, instead of the tree. */
+  readonly tail?: string
 }
 
 export interface WatchOutput {
@@ -64,6 +76,8 @@ export interface WatchDependencies {
   readonly output: WatchOutput
   /** Key names as `onTreeKey` reads them: "up", "enter", "q", … */
   readonly keys: Stream.Stream<string>
+  /** A run's transcript files (`--transcript`); the disk by default. */
+  readonly transcripts?: TranscriptFiles
 }
 
 export class WatchTargetMissing extends Schema.TaggedError<WatchTargetMissing>()(
@@ -184,20 +198,42 @@ const readInputs = (
 const pollInterval = Duration.millis(500)
 const replayGapCap = 2_000
 
-const draw = (state: TreeState, view: TreeView, output: WatchOutput, height?: number): string =>
+const draw = (
+  state: TreeState,
+  view: TreeView,
+  output: WatchOutput,
+  height?: number,
+  tail?: ReadonlyArray<string>
+): string =>
   renderTree(state, {
     width: Math.max(90, output.columns() ?? 90),
     colour: output.colour,
     view,
-    ...(height === undefined ? {} : { height })
+    ...(height === undefined ? {} : { height }),
+    ...(tail === undefined ? {} : { tail })
   }).join("\n")
 
 /** A full-screen frame: no taller than the terminal. */
 const screenLines = (
   state: TreeState,
   view: TreeView,
-  output: WatchOutput
-): ReadonlyArray<string> => draw(state, view, output, output.rows()).split("\n")
+  output: WatchOutput,
+  tail?: ReadonlyArray<string>
+): ReadonlyArray<string> => draw(state, view, output, output.rows(), tail).split("\n")
+
+/** Rows the tail pane shows. */
+const tailRows = 16
+
+/** Where a trace's run kept its transcript: `.llm4ts/transcripts/<run-id>/`. */
+const transcriptDirOf = (
+  repo: string,
+  target: WatchTarget,
+  files: PlainFileStoreShape
+): Effect.Effect<string | undefined, FlowError> =>
+  Effect.map(readTrace(files, target.tracePath), (lines) => {
+    const runId = lines[0]?.runId
+    return runId === undefined ? undefined : join(repo, TraceDirectoryName, "transcripts", runId)
+  })
 
 export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function* (
   options: WatchOptions,
@@ -210,6 +246,39 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
       inputs.reduce(reduceTree, start)
     )
 
+  const transcripts = dependencies.transcripts ?? nodeTranscriptFiles
+  const transcriptDir = yield* transcriptDirOf(options.repo, target, files)
+
+  if (options.tail !== undefined) {
+    if (transcriptDir === undefined || transcripts.list(transcriptDir).length === 0) {
+      return yield* WatchTargetMissing.make({
+        message: "no transcript for this run — start it with llm4ts run … --transcript"
+      })
+    }
+    return yield* followTail(options.tail, transcriptDir, transcripts, output, () =>
+      Effect.map(readInputs(target, files), (inputs) =>
+        inputs.some((input) => input._tag === "RunEnded")
+      )
+    )
+  }
+
+  /** The open tail's lines, for the view's selection. */
+  const tailFor = (view: TreeView): Effect.Effect<ReadonlyArray<string> | undefined> => {
+    const selected = tailTargetOf(view)
+    return !view.tail || selected === undefined || transcriptDir === undefined
+      ? Effect.succeed(undefined)
+      : Effect.map(loadTranscript(transcripts, transcriptDir, selected), (entries) =>
+          tailLinesOf(
+            entries,
+            selected,
+            view.tailRole,
+            Math.max(90, output.columns() ?? 90) - 32,
+            tailRows,
+            view.tailBack
+          )
+        )
+  }
+
   if (!output.interactive) {
     const state = yield* Effect.flatMap(readInputs(target, files), fold)
     return yield* output.write(`${draw(state, initialView, output)}\n`)
@@ -264,7 +333,7 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
               ? reduceTree(folded, { _tag: "Tick", at: yield* Clock.currentTimeMillis })
               : folded
           const text = yield* painter.paint(
-            screenLines(state, yield* Ref.get(view), output),
+            screenLines(state, yield* Ref.get(view), output, yield* tailFor(yield* Ref.get(view))),
             `${output.columns()}x${output.rows()}`
           )
           if (text.length > 0) {
@@ -322,3 +391,55 @@ export const nodeWatchDependencies = (
     keys: nodeTreeKeys("detach")
   }
 }
+
+// ── tail ────────────────────────────────────────────────────────────────────
+
+/**
+ * `llm4ts watch --tail <story|executor>`: the transcript printed as it grows,
+ * like `tail -f` — a call's reply streams in as written — until the run ends.
+ * A name with its own file is a story; any other is an executor.
+ */
+const followTail = (
+  name: string,
+  directory: string,
+  transcripts: TranscriptFiles,
+  output: WatchOutput,
+  ended: () => Effect.Effect<boolean, FlowError>
+): Effect.Effect<void, FlowError> =>
+  Effect.gen(function* () {
+    const target: TailTarget = transcripts.list(directory).includes(transcriptFileOf(name))
+      ? { lane: name }
+      : { executor: name }
+    const width = Math.max(60, output.columns() ?? 100)
+    let shown = 0
+    let start: number | undefined
+    const wanted = new Set<string>()
+    let replying: string | undefined
+    while (true) {
+      const done = yield* ended()
+      const entries = (yield* loadTranscript(transcripts, directory, target)) ?? []
+      for (const entry of entries.slice(shown)) {
+        start = start ?? entry.at
+        if (entry._tag === "Call" && ("lane" in target || entry.executor === target.executor)) {
+          wanted.add(entry.call)
+        }
+        if (!wanted.has(entry.call)) {
+          continue
+        }
+        if (entry._tag === "Reply") {
+          // A reply streams: its text as it arrived, on one growing paragraph.
+          yield* output.write(`${replying === entry.call ? "" : "◀ "}${entry.text}`)
+          replying = entry.call
+          continue
+        }
+        const lines = renderTranscript([entry], { width, since: start })
+        yield* output.write(`${replying === undefined ? "" : "\n"}${lines.join("\n")}\n`)
+        replying = undefined
+      }
+      shown = entries.length
+      if (done) {
+        return
+      }
+      yield* Effect.sleep(pollInterval)
+    }
+  })