@llm4ts/flow 2.31.0 → 2.32.0

package/src/Chat.ts

@@ -3,9 +3,10 @@ import * as Ref from "effect/Ref"
 import * as Semaphore from "effect/Semaphore"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { Message, type LlmResponse } from "@llm4ts/core/Models"
-import { collect } from "@llm4ts/core/Streaming"
+import { collectAny } from "@llm4ts/core/Streaming"
 import { withToolActivity } from "./Activity.ts"
-import { FlowLlmError } from "./FlowError.ts"
+import { FlowLlmError, type Stalled } from "./FlowError.ts"
+import { noRepeats, stallGuard, type StallOptions } from "./Stall.ts"
 import { Info, TokensUsed, type FlowEventsShape } from "./FlowEvents.ts"
 import { isContextOverflow } from "./TransientRetry.ts"
 
@@ -24,6 +25,8 @@ export interface ChatOptions {
   readonly events?: FlowEventsShape
   /** Request label for published `TokensUsed` events. Default: "chat". */
   readonly agent?: string
+  /** End a turn that repeats one tool call or goes silent (ADR 0027 decision 11). */
+  readonly stall?: StallOptions
 }
 
 const publishUsage = (options: ChatOptions, response: LlmResponse): Effect.Effect<void> =>
@@ -38,7 +41,7 @@ const publishUsage = (options: ChatOptions, response: LlmResponse): Effect.Effec
       )
 
 export interface Chat {
-  readonly ask: (prompt: string) => Effect.Effect<string, FlowLlmError>
+  readonly ask: (prompt: string) => Effect.Effect<string, FlowLlmError | Stalled>
   readonly messages: Effect.Effect<ReadonlyArray<Message>>
 }
 
@@ -60,15 +63,19 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
 ): Effect.fn.Return<Chat> {
   const history = yield* Ref.make(initialHistory(options))
   const gate = yield* Semaphore.make(1)
+  const repeats = yield* Ref.make(noRepeats)
 
   const send = (messages: ReadonlyArray<Message>) => {
     const stream = service.executeStreamWithHistory(messages)
-    return collect(options.events === undefined ? stream : withToolActivity(options.events, stream))
+    const watched = options.events === undefined ? stream : withToolActivity(options.events, stream)
+    return collectAny(
+      options.stall === undefined ? watched : stallGuard(watched, options.stall, repeats)
+    )
   }
 
   const askRound = Effect.fn("@llm4ts/flow/Chat.ask")(function* (
     prompt: string
-  ): Effect.fn.Return<string, FlowLlmError> {
+  ): Effect.fn.Return<string, FlowLlmError | Stalled> {
     const userTurn = Message.make({ role: "User", content: prompt })
     const earlier = yield* Ref.get(history)
     const full = [...earlier, userTurn]
@@ -81,7 +88,8 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
     // this turn alone, and continue the conversation from there.
     const response = yield* send(full).pipe(
       Effect.catchIf(
-        (error) => isContextOverflow(error) && full.length > system.length + 1,
+        (error) =>
+          error._tag !== "Stalled" && isContextOverflow(error) && full.length > system.length + 1,
         (error) =>
           Effect.gen(function* () {
             messages = [
@@ -106,7 +114,7 @@ export const makeChat = Effect.fn("@llm4ts/flow/Chat.make")(function* (
             return yield* send(messages)
           })
       ),
-      Effect.mapError(FlowLlmError.from)
+      Effect.mapError((error) => (error._tag === "Stalled" ? error : FlowLlmError.from(error)))
     )
     yield* publishUsage(options, response)
     yield* Ref.set(history, [

package/src/Flow.ts

@@ -44,6 +44,8 @@ import {
 } from "./Review.ts"
 import type { OracleRules } from "./OracleGuard.ts"
 import type { Reviewer } from "./Reviewer.ts"
+import { withContract } from "./AutonomyContract.ts"
+import type { StallOptions } from "./Stall.ts"
 
 export { publishUsage, structuredAndPublish } from "./Usage.ts"
 
@@ -109,6 +111,18 @@ export interface ImplementPlanOptions {
    * `testsChange` is true.
    */
   readonly oracle?: { readonly rules?: OracleRules; readonly testsChange?: boolean }
+  /** Independent votes of the adversarial lens per round (ADR 0027 decision 7). Default 1. */
+  readonly votes?: number
+  /**
+   * Who applies review findings (ADR 0027 decision 8): the implementer's own
+   * chat (default), or a fresh chat on the coder seat briefed to apply the
+   * findings and nothing else, with the carried notes for orientation.
+   */
+  readonly fixer?: "coder" | "separate"
+  /** The repository's own review rules (`.llm4ts/review-rules.md`), loaded by the caller, as one extra lens. */
+  readonly repoRules?: Effect.Effect<Reviewer | undefined, FlowError>
+  /** End a coder turn that repeats one tool call or goes silent (ADR 0027 decision 11). */
+  readonly stall?: StallOptions
   /** How gate output reaches the coder in the fix prompt. */
   readonly fix?: FixPromptOptions
   /** Where each review lens's answer is kept, so a rerun over the same diff asks nothing. */
@@ -211,6 +225,14 @@ const defaultCommitMessage = (plan: Plan, task: Task): string => `${plan.epicId}
 const composeSystem = (base: string | undefined, note: string): string =>
   [base, note].filter((part): part is string => part !== undefined && part.length > 0).join("\n\n")
 
+/** The separate fixer's brief (ADR 0027 decision 8): the Bun port's fixer, word for word in spirit. */
+export const fixerBrief = [
+  "You apply review findings to a change another coder made. Apply the findings. Nothing else.",
+  "Surgical edits only: no refactors, no extras, no new tests beyond what a finding asks for.",
+  "If a finding is wrong (the reviewer misread the code), skip it and say so in one line.",
+  "Then stop."
+].join("\n")
+
 /**
  * The task's triage: the explicit one, or one built from `baseline` over the
  * commit the task starts from (HEAD now), or none.
@@ -258,7 +280,8 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
     sharedCoder = yield* makeChat(context.coder, {
       events: context.events,
       agent: "coder",
-      ...(options.system === undefined ? {} : { system: options.system })
+      ...(options.system === undefined ? {} : { system: options.system }),
+      ...(options.stall === undefined ? {} : { stall: options.stall })
     })
   }
 
@@ -279,7 +302,8 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           coder = yield* makeChat(context.coder, {
             events: context.events,
             agent: "coder",
-            system: composeSystem(options.system, planSoFar.render)
+            system: composeSystem(options.system, planSoFar.render),
+            ...(options.stall === undefined ? {} : { stall: options.stall })
           })
         }
         // `plan.taskPrompt` deliberately reads the frozen `plan` captured at
@@ -354,6 +378,24 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           }
         }
         const triage = yield* triageFor(context, options)
+        const repoRules = options.repoRules === undefined ? undefined : yield* options.repoRules
+        const reviewers = [
+          ...(options.reviewers ?? minimalReviewers),
+          ...(repoRules === undefined ? [] : [repoRules])
+        ]
+        const fixWith =
+          options.fixer === "separate"
+            ? (prompt: string): Effect.Effect<string, FlowError> =>
+                Effect.flatMap(
+                  makeChat(context.coder, {
+                    events: context.events,
+                    agent: "coder",
+                    system: withContract(fixerBrief),
+                    ...(options.stall === undefined ? {} : { stall: options.stall })
+                  }),
+                  (fixer) => fixer.ask(withNotes(prompt, notes))
+                )
+            : undefined
         const oracle: OracleGateOptions | undefined =
           options.oracle === undefined
             ? undefined
@@ -368,7 +410,7 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
                   : { baseCount: Effect.map(triage.baseline, (base) => base?.passedCount) })
               }
         yield* reviewAndFixLoop({
-          reviewers: options.reviewers ?? minimalReviewers,
+          reviewers,
           reviewerService: flowReviewer(context),
           coder,
           taskTitle: task.title,
@@ -379,6 +421,9 @@ export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(fu
           ...(options.format === undefined ? {} : { format: options.format }),
           ...(triage === undefined ? {} : { triage }),
           ...(oracle === undefined ? {} : { oracle }),
+          ...(options.votes === undefined ? {} : { votes: options.votes }),
+          ...(fixWith === undefined ? {} : { fixWith }),
+          ...(options.stall === undefined ? {} : { stallOnIdenticalDiff: true }),
           ...(options.fix === undefined ? {} : { fix: options.fix }),
           ...(options.reviewCache === undefined ? {} : { cache: options.reviewCache }),
           ...(options.onReview === undefined

package/src/FlowError.ts

@@ -267,6 +267,21 @@ export class RosterExhausted extends Schema.TaggedError<RosterExhausted>()("Rost
 }
 
 /** One story failed; carries the story id so a fail-fast run names its cause. */
+/**
+ * A loop that stopped making progress (ADR 0027 decision 11): the review
+ * round saw the same diff twice, the coder repeated one tool call too many
+ * times, or the seat went silent for too long. A stopping condition the
+ * model does not control; the story fails and the retro diagnoses.
+ */
+export class Stalled extends Schema.TaggedError<Stalled>()("Stalled", {
+  signal: Schema.Literals(["identical-diff", "repeated-tool-call", "silence"]),
+  detail: Schema.String
+}) {
+  get message(): string {
+    return `stalled (${this.signal}): ${this.detail}`
+  }
+}
+
 export class StoryFailed extends Schema.TaggedError<StoryFailed>()("StoryFailed", {
   story: Schema.String,
   reason: Schema.String
@@ -371,6 +386,7 @@ export const FlowError = Schema.Union([
   EpicIncomplete,
   LandingFailed,
   StoryFailed,
+  Stalled,
   DecisionsInvalid,
   OpenPointsPending,
   ContractConflict,

package/src/FlowEvents.ts

@@ -171,6 +171,19 @@ export class CapabilityUnenforceable extends Schema.TaggedClass<CapabilityUnenfo
   }
 ) {}
 
+/** A review finding moved down a severity because it could not be placed in the diff (ADR 0027). */
+export class ReviewFindingDemoted extends Schema.TaggedClass<ReviewFindingDemoted>()(
+  "ReviewFindingDemoted",
+  {
+    lens: Schema.String,
+    title: Schema.String,
+    from: Schema.Literals(["Critical", "Warning", "Info"]),
+    to: Schema.Literals(["Critical", "Warning", "Info"]),
+    reason: Schema.String,
+    lane: Schema.optionalKey(Schema.String)
+  }
+) {}
+
 /** A task's `verified:` claims against the tool calls its transcript shows (ADR 0027). */
 export class EvidenceChecked extends Schema.TaggedClass<EvidenceChecked>()("EvidenceChecked", {
   task: Schema.String,
@@ -248,13 +261,15 @@ export class ExecutorLeased extends Schema.TaggedClass<ExecutorLeased>()("Execut
   executor: Schema.String,
   role: Schema.String,
   label: Schema.optionalKey(Schema.String),
-  /** Took the role on its own context's coder slot: nobody independent could. */
+  /** Took the role on its own context's coder slot, no slot of its own free: nobody independent could. */
   borrowed: Schema.optionalKey(Schema.Boolean),
   /**
-   * Why it borrowed: `nobody` else takes the role (or all are out for the
-   * run); `held`: every other executor that could has its slots held by coders.
+   * Set when the executor is the context's own coder, so the call is not
+   * independent: `nobody` else takes the role (or all are out for the run);
+   * `held`: every other executor that could has its slots held by coders;
+   * `out`: every other executor that could is out of the round for now.
    */
-  because: Schema.optionalKey(Schema.Literals(["nobody", "held"]))
+  because: Schema.optionalKey(Schema.Literals(["nobody", "held", "out"]))
 }) {}
 
 export class ExecutorReleased extends Schema.TaggedClass<ExecutorReleased>()("ExecutorReleased", {
@@ -309,14 +324,21 @@ export const rosterEventMessage = (event: FlowEvent): string | undefined => {
   const forLabel = (label: string | undefined): string =>
     label === undefined ? "" : ` for ${label}`
   switch (event._tag) {
-    case "ExecutorLeased":
+    case "ExecutorLeased": {
+      const taken = `roster: ${event.executor} takes ${event.role}${forLabel(event.label)}`
+      if (event.because === undefined && event.borrowed !== true) {
+        return taken
+      }
+      const why =
+        event.because === "held"
+          ? `every other executor that takes ${event.role} is held by a coder`
+          : event.because === "out"
+            ? `every other executor that takes ${event.role} is out of the round`
+            : `no other executor can take ${event.role}`
       return event.borrowed === true
-        ? `roster: ${event.executor} takes ${event.role}${forLabel(event.label)} on its own coder's slot — not independent (${
-            event.because === "held"
-              ? `every other executor that takes ${event.role} is held by a coder`
-              : `no other executor can take ${event.role}`
-          })`
-        : `roster: ${event.executor} takes ${event.role}${forLabel(event.label)}`
+        ? `${taken} on its own coder's slot — not independent (${why})`
+        : `${taken} on its own slot — not independent (${why})`
+    }
     case "ExecutorExcluded":
       return `roster: ${event.executor} out of the round ${event.reason}`
     case "ExecutorResumed":
@@ -347,6 +369,7 @@ export const FlowEvent = Schema.Union([
   CapabilityDeniedEvent,
   CapabilityUnenforceable,
   EvidenceChecked,
+  ReviewFindingDemoted,
   Declassified,
   ExecutorLeased,
   ExecutorReleased,

package/src/Pack.ts

@@ -4,7 +4,7 @@ import { Dimension } from "@llm4ts/core/eval/Eval"
 import type { ConsolidateRules } from "./Domains.ts"
 import { PlanParseError } from "./FlowError.ts"
 import { oracleRulesFrom, type OracleRules } from "./OracleGuard.ts"
-import { parseReviewer, type Reviewer } from "./Reviewer.ts"
+import { Reviewer, parseReviewer } from "./Reviewer.ts"
 import { CoverageRule } from "./SpecChecks.ts"
 import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
 
@@ -74,6 +74,11 @@ export interface Pack {
    * over the defaults. Absent: the defaults.
    */
   readonly oracle: OracleRules | undefined
+  /**
+   * The `## Review rules` section (ADR 0027 decision 9): extra rules every
+   * pack lens carries after the shared preamble, or `- preamble: off`.
+   */
+  readonly reviewRules: { readonly text: string; readonly preamble: boolean } | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
@@ -237,9 +242,36 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
   const gates = Object.fromEntries(
     Object.entries(gateValues).map(([name, command]) => [name, command.split(/\s+/)])
   )
+  const reviewRulesBody = section(manifest.sections, "Review rules")
+  const reviewRulesValues = namedItems(reviewRulesBody)
+  const reviewRules =
+    reviewRulesBody === undefined
+      ? undefined
+      : {
+          text: reviewRulesBody
+            .split(/\r?\n/)
+            .filter((line) => !/^- preamble:/iu.test(line.trim()))
+            .join("\n")
+            .trim(),
+          preamble: reviewRulesValues.preamble?.toLowerCase() !== "off"
+        }
   const lenses = Object.entries(lensFiles)
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, text]) => parseReviewer(name, text))
+    // The pack's own review rules ride on every lens; `preamble: off` leaves
+    // the shared preamble out (ADR 0027 decision 9).
+    .map((lens) =>
+      reviewRules === undefined
+        ? lens
+        : Reviewer.make({
+            ...lens,
+            systemPrompt:
+              reviewRules.text.length === 0
+                ? lens.systemPrompt
+                : `${lens.systemPrompt}\n\nPack review rules:\n${reviewRules.text}`,
+            ...(reviewRules.preamble ? {} : { preamble: false })
+          })
+    )
   const fields = manifest.fields
   if (fields["programFiles"] !== undefined) {
     return yield* PlanParseError.make({
@@ -346,6 +378,7 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     specSchema,
     consolidate,
     oracle,
+    reviewRules,
     dir: directory,
     gate: (name) => gates[name],
     prompt: (name) => prompts[name],

package/src/ProgramJudge.ts

@@ -1,3 +1,4 @@
+import { reviewRulesPreamble } from "./Review.ts"
 import * as Effect from "effect/Effect"
 import { Sample, type Dimension, type EvalResult } from "@llm4ts/core/eval/Eval"
 import { makeEvaluator, type Evaluator } from "@llm4ts/core/eval/Evaluator"
@@ -141,7 +142,9 @@ export const withJudgment = (
 const join = (root: string, path: string): string =>
   `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
 
+/** The shared review rules (ADR 0027 decision 9) precede every rubric the judge scores with. */
 const rubricText = (dimensions: ReadonlyArray<Dimension>): string =>
+  `${reviewRulesPreamble}\n\n` +
   dimensions
     .map((dimension) => `${dimension.name} (0..${dimension.maxScore}): ${dimension.rubric}`)
     .join("\n")