@llm4ts/flow 2.31.0 → 2.32.0

package/src/Roster.ts

@@ -395,6 +395,8 @@ export interface Lease {
   readonly release: Effect.Effect<void>
   /** Took no slot: the context's own coder executor serves the call (see `LeaseOptions.borrow`). */
   readonly borrowed: boolean
+  /** Set when the executor is the context's own coder (not independent), and why; see `ExecutorLeased.because`. */
+  readonly because?: "nobody" | "held" | "out"
 }
 
 export interface LeaseOptions {
@@ -405,15 +407,16 @@ export interface LeaseOptions {
   /** Who is asking, for the events (a story's worktree). */
   readonly label?: string
   /**
-   * The executor holding this context's coder, used without a slot (its
-   * coder is idle while the context makes this call) when independence
-   * cannot be had: no executor outside `avoid` can ever take the role, or
-   * every one in the round that could has all its slots held by coders. A
-   * coder's slot frees only when its story ends, and that story may itself
-   * be waiting on a call like this one — waiting for it would saturate the
-   * roster. An executor that is out of the round is still borrowed in the
-   * first case (the call fails on it, as it would on anyone), never in the
-   * second (a story in the round will free a slot).
+   * The executor holding this context's coder, taken when independence
+   * cannot be had now: no executor outside `avoid` can ever take the role,
+   * every one that could is held by a coder, or every one is out of the
+   * round. A coder's slot frees only when its story ends (which may itself
+   * wait on a call like this one), and an exclusion may last hours; a
+   * reasoning call only ever waits for another call to end. The own
+   * executor is taken on a free slot of its own when it has one, else
+   * without a slot (its coder is idle while the context makes this call).
+   * Out of the round itself, it is still taken when nobody can ever serve
+   * (the call fails on it, as it would on anyone), and waited past otherwise.
    */
   readonly borrow?: ExecutorSpec
 }
@@ -445,6 +448,15 @@ export interface RosterShape {
    * for `role` would then wait for a story to end, not for a call.
    */
   readonly coderHeld: (role: Role, avoid?: ReadonlyArray<string>) => Effect.Effect<boolean>
+  /**
+   * Why a lease for `role` outside `avoid` cannot be served by a call
+   * ending: `held` (every executor in the round is held by coders), `out`
+   * (none is in the round), or `undefined` when one has a slot a call frees.
+   */
+  readonly independenceBlocked: (
+    role: Role,
+    avoid?: ReadonlyArray<string>
+  ) => Effect.Effect<"held" | "out" | undefined>
   /** Free slots for `role` now, across executors in the round. */
   readonly available: (role: Role) => Effect.Effect<number>
   /** Configured slots for `role`. */
@@ -574,11 +586,13 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
   const leaseOf = (
     spec: ExecutorSpec,
     role: Role,
-    label: string | undefined
+    label: string | undefined,
+    because?: "nobody" | "held" | "out"
   ): Effect.Effect<Lease, never, Scope.Scope> =>
     Effect.gen(function* () {
       const labelled = label === undefined ? {} : { label }
-      yield* events.publish(ExecutorLeased.make({ executor: spec.id, role, ...labelled }))
+      const own = because === undefined ? {} : { because }
+      yield* events.publish(ExecutorLeased.make({ executor: spec.id, role, ...labelled, ...own }))
       const done = yield* Ref.make(false)
       const free = Effect.flatMap(Ref.getAndSet(done, true), (was) =>
         was
@@ -589,7 +603,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
             )
       )
       yield* Effect.addFinalizer(() => free)
-      return { executor: spec, role, release: free, borrowed: false }
+      return { executor: spec, role, release: free, borrowed: false, ...own }
     })
 
   /** A lease over the context's own coder executor: no slot taken, none freed. */
@@ -597,7 +611,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     spec: ExecutorSpec,
     role: Role,
     label: string | undefined,
-    because: "nobody" | "held"
+    because: "nobody" | "held" | "out"
   ): Effect.Effect<Lease, never, Scope.Scope> =>
     Effect.gen(function* () {
       const labelled = label === undefined ? {} : { label }
@@ -611,7 +625,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
           : events.publish(ExecutorReleased.make({ executor: spec.id, role, ...labelled }))
       )
       yield* Effect.addFinalizer(() => free)
-      return { executor: spec, role, release: free, borrowed: true }
+      return { executor: spec, role, release: free, borrowed: true, because }
     })
 
   /** One attempt: expire, pick, take the slot — all under the lock. */
@@ -660,18 +674,26 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       )
     )
 
-  const coderHeld = (role: Role, avoid: ReadonlyArray<string> = []): Effect.Effect<boolean> =>
-    lock.withPermit(
-      Effect.sync(() => {
-        const inRound = eligible(role, avoid)
-        return (
-          inRound.length > 0 &&
-          inRound.every(
-            (spec) => (usage.get(spec.id) ?? { busy: 0, busyCoders: 0 }).busyCoders >= slotsOf(spec)
-          )
-        )
-      })
+  const blockedOutside = (role: Role, avoid: ReadonlyArray<string>): "held" | "out" | undefined => {
+    const inRound = eligible(role, avoid)
+    if (inRound.length === 0) {
+      return "out"
+    }
+    return inRound.every(
+      (spec) => (usage.get(spec.id) ?? { busy: 0, busyCoders: 0 }).busyCoders >= slotsOf(spec)
     )
+      ? "held"
+      : undefined
+  }
+
+  const independenceBlocked = (
+    role: Role,
+    avoid: ReadonlyArray<string> = []
+  ): Effect.Effect<"held" | "out" | undefined> =>
+    lock.withPermit(Effect.sync(() => blockedOutside(role, avoid)))
+
+  const coderHeld = (role: Role, avoid: ReadonlyArray<string> = []): Effect.Effect<boolean> =>
+    Effect.map(independenceBlocked(role, avoid), (blocked) => blocked === "held")
 
   /** Probes every `health` exclusion whose next probe is due; a live one comes back. */
   const probeDue: Effect.Effect<void> = Effect.gen(function* () {
@@ -771,13 +793,37 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         leaseOptions.borrow !== undefined && hasRole(leaseOptions.borrow, role)
           ? leaseOptions.borrow
           : undefined
-      /** Borrowing when the round is held by coders needs an executor in the round. */
-      const borrowInRound = (): Effect.Effect<ExecutorSpec | undefined> =>
-        lock.withPermit(
-          Effect.sync(() =>
-            borrow !== undefined && !exclusions.has(borrow.id) ? borrow : undefined
-          )
-        )
+      /**
+       * Independence cannot be had now: the context's own executor, when in
+       * the round, takes the call — on a free slot of its own, else without
+       * one (its coder is idle while the context makes this call).
+       */
+      const takeOwn = (
+        because: "nobody" | "held" | "out"
+      ): Effect.Effect<Lease | undefined, never, Scope.Scope> =>
+        Effect.gen(function* () {
+          if (borrow === undefined) {
+            return undefined
+          }
+          // Out of the round itself, the own executor is still taken when
+          // nobody else can ever serve (the call fails on it, as on anyone).
+          const inRound = yield* lock.withPermit(Effect.sync(() => !exclusions.has(borrow.id)))
+          if (!inRound && because !== "nobody") {
+            return undefined
+          }
+          const own = yield* attempt(role, {
+            ...leaseOptions,
+            avoid: avoid.filter((id) => id !== borrow.id),
+            prefer: borrow.id
+          })
+          yield* waited
+          return own !== undefined && own.id === borrow.id
+            ? yield* leaseOf(own, role, leaseOptions.label, because)
+            : own !== undefined
+              ? // Someone came back between the check and the pick: independent after all.
+                yield* leaseOf(own, role, leaseOptions.label)
+              : yield* borrowedLease(borrow, role, leaseOptions.label, because)
+        })
       let announced = false
       const asked = yield* Clock.currentTimeMillis
       // A lease that had to wait says how long, for the story it is for.
@@ -800,9 +846,9 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
           return yield* leaseOf(spec, role, leaseOptions.label)
         }
         if (!(yield* canEverServe(role, avoid))) {
-          if (borrow !== undefined) {
-            yield* waited
-            return yield* borrowedLease(borrow, role, leaseOptions.label, "nobody")
+          const own = yield* takeOwn("nobody")
+          if (own !== undefined) {
+            return own
           }
           const reasons = yield* lock.withPermit(
             Effect.sync(() =>
@@ -819,11 +865,11 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
             reasons: reasons.length === 0 ? ["no executor in the roster takes this role"] : reasons
           })
         }
-        if (yield* coderHeld(role, avoid)) {
-          const own = yield* borrowInRound()
+        const blocked = yield* independenceBlocked(role, avoid)
+        if (blocked !== undefined) {
+          const own = yield* takeOwn(blocked)
           if (own !== undefined) {
-            yield* waited
-            return yield* borrowedLease(own, role, leaseOptions.label, "held")
+            return own
           }
         }
         if (!announced) {
@@ -956,6 +1002,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     tryLease,
     canEverServe,
     coderHeld,
+    independenceBlocked,
     available,
     slots,
     report,

package/src/RosterSeats.ts

@@ -15,6 +15,7 @@ import { describeFlowError, type FlowError } from "./FlowError.ts"
 import { ExecutorHandedOver, type FlowEventsShape } from "./FlowEvents.ts"
 import {
   describeExclusion,
+  hasRole,
   type ExecutorSpec,
   type Lease,
   type Role,
@@ -104,9 +105,10 @@ export interface RosterSeatOptions {
   /** Executors this seat must not use: the context's coder, for independence. */
   readonly avoid?: Effect.Effect<ReadonlyArray<string>>
   /**
-   * The context's coder executor, used without a slot when independence
-   * cannot be had: nobody outside `avoid` can ever serve the role, or every
-   * executor that could is held by a coder (`LeaseOptions.borrow`).
+   * The context's coder executor, taken when independence cannot be had —
+   * nobody outside `avoid` can ever serve the role, every executor that
+   * could is held by a coder, or out of the round — on a free slot of its
+   * own, or without one (`LeaseOptions.borrow`).
    */
   readonly borrow?: Effect.Effect<ExecutorSpec | undefined>
   /** Who is asking, for the events. */
@@ -150,8 +152,9 @@ export const rosterSeat = (
 
   /**
    * After a failure that took `executor` out of the round, whether another
-   * executor can still take the call: the call moves once, never twice — a
-   * second failure is the call's own, not the executor's.
+   * executor can still take the call — an independent one, or the context's
+   * own: the call moves once, never twice — a second failure is the call's
+   * own, not the executor's.
    */
   const retryElsewhere = (
     executor: ExecutorSpec,
@@ -164,7 +167,9 @@ export const rosterSeat = (
         return false
       }
       const avoid = options.avoid === undefined ? [] : yield* options.avoid
-      const other = yield* roster.canEverServe(role, [...avoid, executor.id])
+      const borrow = options.borrow === undefined ? undefined : yield* options.borrow
+      const own = borrow !== undefined && borrow.id !== executor.id && hasRole(borrow, role)
+      const other = own || (yield* roster.canEverServe(role, [...avoid, executor.id]))
       if (other) {
         yield* options.events.publish(
           ExecutorHandedOver.make({

package/src/Stall.ts

@@ -0,0 +1,85 @@
+// Stopping conditions the model does not control (ADR 0027 decision 11).
+// Pure helpers over a chat's chunk stream; `Chat` applies them when asked.
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
+import type { LlmError } from "@llm4ts/core/Errors"
+import type { LlmChunk } from "@llm4ts/core/Models"
+import { Stalled } from "./FlowError.ts"
+
+export interface StallOptions {
+  /** The same tool call with the same arguments this many times in a row ends the turn. Default 5. */
+  readonly repeats?: number
+  /** No chunk for this long ends the turn; absent means never (a slow seat looks like silence). */
+  readonly silence?: Duration.Duration
+}
+
+export const defaultStallRepeats = 5
+
+/** The identity of a tool call chunk: name and arguments; `undefined` for anything else. */
+export const toolCallKey = (chunk: LlmChunk): string | undefined =>
+  chunk.metadata.event === "tool_use"
+    ? `${chunk.metadata.tool_name ?? chunk.metadata.toolName ?? ""}|${chunk.metadata.tool_input ?? chunk.metadata.toolInput ?? ""}`
+    : undefined
+
+export interface RepeatState {
+  readonly key: string | undefined
+  readonly count: number
+}
+
+export const noRepeats: RepeatState = { key: undefined, count: 0 }
+
+/** The repeat state after one chunk: a different call resets, the same one counts. */
+export const nextRepeat = (state: RepeatState, chunk: LlmChunk): RepeatState => {
+  const key = toolCallKey(chunk)
+  if (key === undefined) {
+    return state
+  }
+  return key === state.key ? { key, count: state.count + 1 } : { key, count: 1 }
+}
+
+/**
+ * The stream, ended with `Stalled` when one tool call repeats `repeats`
+ * times in a row (the state is shared across a chat's turns through `state`)
+ * or when no chunk arrives within `silence`.
+ */
+export const stallGuard = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  options: StallOptions,
+  state: Ref.Ref<RepeatState>
+): Stream.Stream<LlmChunk, LlmError | Stalled, R> => {
+  const limit = Math.max(2, options.repeats ?? defaultStallRepeats)
+  const counted = Stream.mapEffect(stream, (chunk) =>
+    Effect.flatMap(
+      Ref.modify(state, (current) => {
+        const next = nextRepeat(current, chunk)
+        return [next, next] as const
+      }),
+      (next) =>
+        next.count >= limit
+          ? Effect.fail(
+              Stalled.make({
+                signal: "repeated-tool-call",
+                detail: `the same tool call ${next.count} times in a row: ${(next.key ?? "").slice(0, 200)}`
+              })
+            )
+          : Effect.succeed(chunk)
+    )
+  )
+  const silence = options.silence
+  return silence === undefined
+    ? counted
+    : counted.pipe(
+        Stream.timeoutOrElse({
+          duration: silence,
+          orElse: () =>
+            Stream.fail(
+              Stalled.make({
+                signal: "silence",
+                detail: `no output for ${Duration.format(silence)} (LLM4TS_STALL_MINUTES)`
+              })
+            )
+        })
+      )
+}

package/src/Stories.ts

@@ -72,6 +72,7 @@ import {
   ReviewIssue,
   ReviewResult,
   applyTriage,
+  loadRepoReviewRules,
   type FixPromptOptions,
   type GateTriageOptions
 } from "./Review.ts"
@@ -85,6 +86,7 @@ import { cachedValue, fingerprintOf } from "./ReviewCache.ts"
 import { withContract, type ContractProfile } from "./AutonomyContract.ts"
 import { fabricatedStatusIssues, unverifiedClaims } from "./Evidence.ts"
 import type { Trailer } from "./CarriedNotes.ts"
+import type { StallOptions } from "./Stall.ts"
 import type { Reviewer } from "./Reviewer.ts"
 import {
   dependentsOf,
@@ -659,6 +661,12 @@ export interface StoriesOptions {
   readonly fix?: FixPromptOptions
   /** Test-file and marker patterns for the oracle guard; default rules when absent (ADR 0027). */
   readonly oracleRules?: OracleRules
+  /** Independent votes of the adversarial lens per review round (ADR 0027 decision 7). Default 1. */
+  readonly votes?: number
+  /** Who applies review findings: the implementer's chat (default) or a separate fixer (ADR 0027 decision 8). */
+  readonly fixer?: "coder" | "separate"
+  /** End a coder turn that repeats one tool call or goes silent (ADR 0027 decision 11). */
+  readonly stall?: StallOptions
   /**
    * The autonomy contract profile for the coder's system prompt (ADR 0027
    * decision 5). Default: the roster executor's `contract`, else `full`.
@@ -1447,6 +1455,12 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           result
         ),
       onTaskReply: (task, _reply, trailer, startedAt) => checkEvidence(task, trailer, startedAt),
+      // The repository's own review rules ride along as one extra lens
+      // (ADR 0027 decision 9), read from the epic checkout.
+      repoRules: loadRepoReviewRules(files, context.workDir),
+      ...(options.votes === undefined ? {} : { votes: options.votes }),
+      ...(options.fixer === undefined ? {} : { fixer: options.fixer }),
+      ...(options.stall === undefined ? {} : { stall: options.stall }),
       ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
       ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
     })