@llm4ts/flow 2.21.1 → 2.22.1

package/src/Stories.ts

@@ -4,6 +4,7 @@
 // merges back only after its judge and perimeter checks pass, and the
 // target's gates run on the epic branch after every merge. Scheduling,
 // gating, resume and failure policy live here; seats come from `contextFor`.
+import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
 import * as Queue from "effect/Queue"
@@ -28,7 +29,15 @@ import {
   StoryFailed,
   type FlowError
 } from "./FlowError.ts"
-import { Info, JudgedDimension, StoryJudged, withLane, type FlowEventsShape } from "./FlowEvents.ts"
+import {
+  Info,
+  JudgedDimension,
+  StoryJudged,
+  Timed,
+  withLane,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
+import { timeEffect } from "./Timing.ts"
 import { statusPaths, type GitToolShape } from "./GitTool.ts"
 import {
   checkPerimeter,
@@ -44,10 +53,10 @@ import {
   saveVersioned,
   type PlainFileStoreShape
 } from "./Persistence.ts"
-import { Plan } from "./Plan.ts"
+import { Plan, Task } from "./Plan.ts"
 import { stage } from "./PlanExecution.ts"
 import { planFrom } from "./Planner.ts"
-import { ReviewResult } from "./Review.ts"
+import { ReviewIssue, ReviewResult } from "./Review.ts"
 import type { Reviewer } from "./Reviewer.ts"
 import {
   dependentsOf,
@@ -464,7 +473,7 @@ export interface StoriesOptions {
    * installed dependencies, so the gates cannot run there without this.
    * Runs on every start and resume; a failure fails the story.
    */
-  readonly setup?: (workDir: string) => Effect.Effect<void, FlowError>
+  readonly setup?: (workDir: string, events?: FlowEventsShape) => Effect.Effect<void, FlowError>
   /**
    * When setup fails, give the story's coder ONE turn to make the worktree
    * ready (install, warm a cache, generate a client), then run setup again as
@@ -473,14 +482,30 @@ export interface StoriesOptions {
    */
   readonly setupAgent?: boolean
   /** The target's gates, run in a worktree per task and on the epic checkout after each merge. */
-  readonly gates: (workDir: string) => Effect.Effect<ReviewResult, FlowError>
+  /**
+   * The target's gates in a directory. `events` is the story's lane, so a
+   * gate's timing names its story; a gate may ignore it.
+   */
+  readonly gates: (
+    workDir: string,
+    events?: FlowEventsShape
+  ) => Effect.Effect<ReviewResult, FlowError>
   /** Story-level judge over the branch's diff against the epic branch; omit to skip. */
   readonly judge?: (
     story: Story,
     diff: string,
-    seats: StorySeats
+    seats: StorySeats,
+    /**
+     * `diff`: the branch's changes against the epic. `code`: the branch has
+     * none, so this is the current code of the story's owned paths, to judge
+     * whether the story is already in place.
+     */
+    subject?: "diff" | "code"
   ) => Effect.Effect<ReviewResult, FlowError>
-  /** Judge attempts, each but the last followed by one coder feedback round. Default 2. */
+  /**
+   * Judge attempts, each but the last followed by a revision task on the
+   * story's plan (coder, review, gates, commit). Default 2: one revision.
+   */
   readonly judgeRounds?: number
   /** Extra system context per story (house rules, shared read-only excerpts). */
   readonly system?: (story: Story) => Effect.Effect<string, FlowError>
@@ -570,6 +595,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const judgeRounds = Math.max(1, options.judgeRounds ?? 2)
   const statePath = (story: Story): string => join(options.stateDir, `stories/${story.id}.json`)
   const planPath = (story: Story): string => join(options.stateDir, `stories/${story.id}.plan.md`)
+  /** Git's empty tree: a diff against it is a path's whole current content. */
+  const emptyTree = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+  const revisionTitle = /^Revision \d+: /u
 
   /**
    * The epic checkout must hold nothing uncommitted: every merge and epic
@@ -624,24 +652,37 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
   /** Merge the story branch into the epic branch and re-gate the epic head, one story at a time. */
   const integrate = (story: Story, branch: string): Effect.Effect<void, FlowError> =>
-    mergeLock.withPermit(
-      Effect.gen(function* () {
-        yield* epicCheckoutClean(story)
-        const checkpoint = yield* context.git.checkpoint
-        yield* context.git.merge(branch, `${plan.epicId}: merge story ${story.id}`)
-        const gate = yield* options.gates(context.workDir)
-        if (!gate.isClean) {
-          // Never leave a red epic head for the next story to inherit.
-          yield* context.git.rollback(checkpoint)
-          return yield* failed(
-            story,
-            `epic gates failed after merging; merge undone:\n${issueLines(gate)}`
+    Effect.flatMap(Clock.currentTimeMillis, (requested) =>
+      mergeLock.withPermit(
+        Effect.gen(function* () {
+          const lane = laneOf(story)
+          // Merges are one at a time: how long this story queued for its turn.
+          const turn = yield* Clock.currentTimeMillis
+          yield* lane.publish(
+            Timed.make({ kind: "wait", label: "merge lock", ms: turn - requested })
           )
-        }
-        yield* laneOf(story).publish(
-          Info.make({ message: `story ${story.id}: merged into ${epicBranch}` })
-        )
-      })
+          yield* epicCheckoutClean(story)
+          const checkpoint = yield* context.git.checkpoint
+          yield* timeEffect(
+            lane,
+            context.git.merge(branch, `${plan.epicId}: merge story ${story.id}`),
+            (ms, failed) =>
+              Timed.make({ kind: "merge", label: "merge", ms, ...(failed ? { failed } : {}) })
+          )
+          const gate = yield* options.gates(context.workDir, lane)
+          if (!gate.isClean) {
+            // Never leave a red epic head for the next story to inherit.
+            yield* context.git.rollback(checkpoint)
+            return yield* failed(
+              story,
+              `epic gates failed after merging; merge undone:\n${issueLines(gate)}`
+            )
+          }
+          yield* laneOf(story).publish(
+            Info.make({ message: `story ${story.id}: merged into ${epicBranch}` })
+          )
+        })
+      )
     )
 
   /** The worktree and branch for a story, honouring the hash-guarded resume rules. */
@@ -753,6 +794,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   ): Effect.fn.Return<
     {
       readonly judge: string | undefined
+      /** Its branch had no changes and the judge found its code already on the epic. */
+      readonly inPlace: boolean
       readonly totals: TokenUsage | undefined
       readonly executor: string | undefined
     },
@@ -794,7 +837,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     // Catch up before setup: the epic may have changed the manifest too.
     yield* catchUp(story, git)
     if (options.setup !== undefined) {
-      const setup = options.setup(state.worktree)
+      const setup = options.setup(state.worktree, laneOf(story))
       yield* stage(
         laneOf(story),
         `story ${story.id}: setup`,
@@ -835,7 +878,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     // The target's gates plus the perimeter: a stray path is a gate failure
     // the task review loop hands back to the coder before anything commits.
     const gates: Effect.Effect<ReviewResult, FlowError> = Effect.gen(function* () {
-      const target = yield* options.gates(state.worktree)
+      const target = yield* options.gates(state.worktree, laneOf(story))
       const changed = yield* perimeterNow(story, git)
       return combined(target, perimeterGate([...changed.sharedReadOnly, ...changed.outside], story))
     })
@@ -980,17 +1023,62 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     yield* catchUp(story, git)
     yield* repairPerimeter
 
+    // A judge finding becomes a revision task on the story's own plan, run by
+    // the task loop like any other: coder, review, gates, commit.
+    const addRevision = (verdict: ReviewResult, empty: boolean): Effect.Effect<void, FlowError> =>
+      Effect.gen(function* () {
+        const store = makePlanStore(files)
+        const current = yield* store.load(planPath(story))
+        if (current === undefined) {
+          return
+        }
+        const number = current.tasks.filter((task) => revisionTitle.test(task.title)).length + 1
+        yield* store.save(
+          planPath(story),
+          Plan.make({
+            ...current,
+            tasks: [
+              ...current.tasks,
+              Task.make({
+                title: `Revision ${number}: close the judge's findings`,
+                description: [
+                  empty
+                    ? `The story "${story.title}" has no changes yet, and what it must provide is not all in place on the epic branch.`
+                    : `The story "${story.title}" was judged short of done.`,
+                  "Close these gaps without weakening any test and without leaving your owned paths:",
+                  issueLines(verdict)
+                ].join("\n")
+              })
+            ]
+          })
+        )
+      })
+
     let judgeNote: string | undefined
+    let inPlace = false
     if (options.judge !== undefined) {
       const judge = options.judge
       for (let round = 1; round <= judgeRounds; round += 1) {
         const diff = yield* git.diffVsBase(epicBranch)
-        if (diff.trim().length === 0) {
-          // Nothing to judge is a deterministic failure, not a model call:
-          // a model asked to score an empty diff scores the prompt instead.
-          return yield* failed(story, "the story branch has no changes against the epic branch")
-        }
-        const verdict = yield* judge(story, diff, watchedSeats)
+        // No changes is not a failure by itself: the story's code may already
+        // be on the epic (an earlier story or run put it there). Judge that
+        // code instead: the owned paths against the empty tree.
+        const empty = diff.trim().length === 0
+        const subject = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff
+        const verdict =
+          empty && subject.trim().length === 0
+            ? // Nothing to judge is decided here, not asked of a model.
+              ReviewResult.make({
+                issues: [
+                  ReviewIssue.make({
+                    severity: "Critical",
+                    title: `nothing exists yet under ${story.owned.join(", ")}`,
+                    description: "The story's owned paths are empty on the epic branch."
+                  })
+                ],
+                summary: `judge:${story.id}`
+              })
+            : yield* judge(story, subject, watchedSeats, empty ? "code" : "diff")
         yield* laneOf(story).publish(
           StoryJudged.make({
             lane: story.id,
@@ -1001,27 +1089,25 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           })
         )
         if (verdict.isClean) {
-          judgeNote = `judge cleared (round ${round})`
+          inPlace = empty
+          judgeNote = empty
+            ? `verified already in place (round ${round})`
+            : `judge cleared (round ${round})`
           break
         }
         if (round >= judgeRounds) {
+          const revisions = `${round - 1} revision${round === 2 ? "" : "s"}`
           return yield* failed(
             story,
-            `judge not cleared after ${judgeRounds} round(s):\n${issueLines(verdict)}`
+            empty
+              ? `the story's code is not in place after ${revisions}, and its branch has no changes:\n${issueLines(verdict)}`
+              : `judge not cleared after ${revisions}:\n${issueLines(verdict)}`
           )
         }
-        yield* guarded(
-          coderTurn(
-            [
-              `The story "${story.title}" scored below the bar. Close these gaps without`,
-              "weakening any test and without leaving your owned paths, then stop:",
-              issueLines(verdict)
-            ].join("\n")
-          ),
-          Effect.void
-        )
+        yield* addRevision(verdict, empty)
+        yield* guarded(implementTasks, implementTasks)
+        yield* catchUp(story, git)
         yield* repairPerimeter
-        yield* commitGreen("address judge feedback", "while addressing judge feedback")
       }
     }
 
@@ -1031,6 +1117,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const history = roster === undefined ? [] : yield* roster.history
     return {
       judge: judgeNote,
+      inPlace,
       totals,
       executor: history.length === 0 ? undefined : history.join(" → ")
     }
@@ -1054,7 +1141,14 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       })
     }
     const result = yield* Effect.scoped(implementStory(story, state))
-    yield* integrate(story, state.branch)
+    if (result.inPlace) {
+      // Verified already on the epic: there is nothing to merge or re-gate.
+      yield* laneOf(story).publish(
+        Info.make({ message: `story ${story.id}: verified already in place; nothing to merge` })
+      )
+    } else {
+      yield* integrate(story, state.branch)
+    }
     const last = result.executor?.split(" → ").at(-1)
     yield* saveVersioned(
       files,

package/src/Timing.ts

@@ -0,0 +1,112 @@
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { LlmChunk } from "@llm4ts/core/Models"
+import { Timed, type FlowEventsShape } from "./FlowEvents.ts"
+
+/**
+ * Where a run's time goes. `timedSeat` decorates a seat so every
+ * call publishes a `Timed{kind:"model"}` when it ends — its wall time, when
+ * its first output came, and the API and tool time the backend reported, if
+ * it did. The events carry the seat's role, never the prompt or the reply.
+ */
+
+const reportedMs = (chunk: LlmChunk, key: string): number | undefined => {
+  const raw = chunk.metadata[key]
+  const value = raw === undefined ? Number.NaN : Number(raw)
+  return Number.isFinite(value) ? value : undefined
+}
+
+/** Times `effect`, publishing what `timed` makes of its duration whether it succeeds or fails. */
+export const timeEffect = <A, E, R>(
+  events: FlowEventsShape,
+  effect: Effect.Effect<A, E, R>,
+  timed: (ms: number, failed: boolean) => Timed
+): Effect.Effect<A, E, R> =>
+  Effect.flatMap(Clock.currentTimeMillis, (start) =>
+    Effect.onExit(effect, (exit) =>
+      Effect.flatMap(Clock.currentTimeMillis, (end) =>
+        events.publish(timed(end - start, Exit.isFailure(exit)))
+      )
+    )
+  )
+
+const timedStream = <E>(
+  events: FlowEventsShape,
+  label: string,
+  stream: Stream.Stream<LlmChunk, E>
+): Stream.Stream<LlmChunk, E> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const start = yield* Clock.currentTimeMillis
+      const first = yield* Ref.make<number | undefined>(undefined)
+      const reported = yield* Ref.make<{ apiMs?: number; toolMs?: number }>({})
+      const failed = yield* Ref.make(false)
+      return stream.pipe(
+        Stream.tap((chunk) =>
+          Effect.gen(function* () {
+            const now = yield* Clock.currentTimeMillis
+            yield* Ref.update(first, (at) => at ?? now - start)
+            const apiMs = reportedMs(chunk, "api_ms")
+            const toolMs = reportedMs(chunk, "tools_ms")
+            if (apiMs !== undefined || toolMs !== undefined) {
+              yield* Ref.update(reported, (current) => ({
+                ...current,
+                ...(apiMs === undefined ? {} : { apiMs }),
+                ...(toolMs === undefined ? {} : { toolMs })
+              }))
+            }
+          })
+        ),
+        Stream.tapError(() => Ref.set(failed, true)),
+        Stream.ensuring(
+          Effect.gen(function* () {
+            const end = yield* Clock.currentTimeMillis
+            const firstMs = yield* Ref.get(first)
+            yield* events.publish(
+              Timed.make({
+                kind: "model",
+                label,
+                ms: end - start,
+                ...(firstMs === undefined ? {} : { firstMs }),
+                ...(yield* Ref.get(reported)),
+                ...((yield* Ref.get(failed)) ? { failed: true } : {})
+              })
+            )
+          })
+        )
+      )
+    })
+  )
+
+export const timedSeat = (
+  service: LlmServiceShape,
+  events: FlowEventsShape,
+  label: string
+): LlmServiceShape => {
+  const model = (ms: number, failed: boolean): Timed =>
+    Timed.make({ kind: "model", label, ms, ...(failed ? { failed: true } : {}) })
+  const batched = service.scoreLabelSequence
+  return {
+    executeStream: (prompt) => timedStream(events, label, service.executeStream(prompt)),
+    executeStreamWithHistory: (messages) =>
+      timedStream(events, label, service.executeStreamWithHistory(messages)),
+    executeWithTools: (prompt, tools) =>
+      timeEffect(events, service.executeWithTools(prompt, tools), model),
+    executeStructured: (prompt, schema, jsonSchema) =>
+      timeEffect(events, service.executeStructured(prompt, schema, jsonSchema), model),
+    executeStructuredWithUsage: (prompt, schema, jsonSchema) =>
+      timeEffect(events, service.executeStructuredWithUsage(prompt, schema, jsonSchema), model),
+    scoreLabels: (prompt, labels) => timeEffect(events, service.scoreLabels(prompt, labels), model),
+    ...(batched === undefined
+      ? {}
+      : {
+          scoreLabelSequence: (prompt: string, labelSets: ReadonlyArray<ReadonlyArray<string>>) =>
+            timeEffect(events, batched(prompt, labelSets), model)
+        }),
+    isAvailable: service.isAvailable
+  }
+}