@llm4ts/flow 2.31.1 → 2.33.0

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 })
     })

package/src/WorkQueue.ts

@@ -0,0 +1,194 @@
+// A mechanical work queue (ADR 0028): many small units with a filesystem
+// "done" predicate, worked in rounds under a concurrency cap, each unit's
+// failure becoming the next round's item, progress persisted as a ledger so
+// a rerun resumes where the run stopped. The Bun port's shape; a story is a
+// feature with a DAG and a judge, a queue item is a file with a predicate.
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { Stalled, describeFlowError, type FlowError } from "./FlowError.ts"
+import {
+  Info,
+  StageCompleted,
+  StageFailed,
+  StageStarted,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export interface QueueItem {
+  readonly id: string
+}
+
+export const Confidence = Schema.Literals(["high", "medium", "low"])
+
+/** One line of the ledger: what happened to one item in one round. */
+export class QueueOutcome extends Schema.Class<QueueOutcome>("QueueOutcome")({
+  id: Schema.String,
+  round: Schema.Int,
+  status: Schema.Literals(["done", "failed"]),
+  ms: Schema.Number,
+  note: Schema.optionalKey(Schema.String),
+  confidence: Schema.optionalKey(Confidence),
+  todos: Schema.optionalKey(Schema.Int),
+  at: Schema.Number
+}) {}
+
+const encodeOutcome = Schema.encodeSync(Schema.fromJsonString(QueueOutcome))
+const decodeOutcome = Schema.decodeUnknownOption(Schema.fromJsonString(QueueOutcome))
+
+/** What a unit of work reports back; the queue records it. */
+export interface WorkResult {
+  readonly note?: string
+  readonly confidence?: "high" | "medium" | "low"
+  readonly todos?: number
+}
+
+export interface RunQueueOptions<Item extends QueueItem> {
+  readonly label: string
+  readonly items: ReadonlyArray<Item>
+  /** The filesystem predicate: an item whose output exists is done, whatever the ledger says. */
+  readonly done: (item: Item) => Effect.Effect<boolean, FlowError>
+  /** One unit of work: implement, review, fix; the queue catches its failure. */
+  readonly work: (item: Item, round: number) => Effect.Effect<WorkResult, FlowError>
+  readonly events: FlowEventsShape
+  readonly concurrency?: number
+  /** Rounds over the items that failed; default 3. */
+  readonly maxRounds?: number
+  /** Where outcomes are appended, one JSON line each; omit to keep none. */
+  readonly ledger?: { readonly files: PlainFileStoreShape; readonly path: string }
+  /** After every round: the done items of that round, for a commit. */
+  readonly afterRound?: (
+    round: number,
+    done: ReadonlyArray<Item>,
+    failed: ReadonlyArray<Item>
+  ) => Effect.Effect<void, FlowError>
+}
+
+export interface QueueReport<Item extends QueueItem> {
+  readonly outcomes: ReadonlyArray<QueueOutcome>
+  readonly rounds: number
+  /** Items still not done when the queue stopped. */
+  readonly pending: ReadonlyArray<Item>
+  /** Items that were already done before the first round (a resume). */
+  readonly skipped: ReadonlyArray<Item>
+}
+
+export const readLedger = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<ReadonlyArray<QueueOutcome>, FlowError> =>
+  Effect.map(files.read(path), (text) =>
+    (text ?? "")
+      .split("\n")
+      .filter((line) => line.trim().length > 0)
+      .flatMap((line) => {
+        const decoded = decodeOutcome(line)
+        return decoded._tag === "Some" ? [decoded.value] : []
+      })
+  )
+
+/**
+ * Works the items that are not done, round after round, until every item is
+ * done, the rounds run out, or a round makes no progress (typed `Stalled`).
+ */
+export const runQueue = Effect.fn("@llm4ts/flow/WorkQueue.run")(function* <Item extends QueueItem>(
+  options: RunQueueOptions<Item>
+): Effect.fn.Return<QueueReport<Item>, FlowError> {
+  const concurrency = Math.max(1, options.concurrency ?? 4)
+  const maxRounds = Math.max(1, options.maxRounds ?? 3)
+  const outcomes: Array<QueueOutcome> = []
+  const record = (outcome: QueueOutcome): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
+      outcomes.push(outcome)
+      if (options.ledger !== undefined) {
+        yield* options.ledger.files.append(options.ledger.path, `${encodeOutcome(outcome)}\n`)
+      }
+    })
+
+  const skipped: Array<Item> = []
+  let pending: Array<Item> = []
+  for (const item of options.items) {
+    if (yield* options.done(item)) {
+      skipped.push(item)
+    } else {
+      pending.push(item)
+    }
+  }
+  if (skipped.length > 0) {
+    yield* options.events.publish(
+      Info.make({
+        message: `${options.label}: ${skipped.length} of ${options.items.length} item(s) already done; ${pending.length} to go`
+      })
+    )
+  }
+
+  let rounds = 0
+  while (pending.length > 0 && rounds < maxRounds) {
+    rounds += 1
+    const round = rounds
+    yield* options.events.publish(
+      Info.make({ message: `${options.label}: round ${round}, ${pending.length} item(s)` })
+    )
+    const results = yield* Effect.forEach(
+      pending,
+      (item) =>
+        Effect.gen(function* () {
+          const stage = `${options.label} ${item.id}`
+          yield* options.events.publish(StageStarted.make({ stage, lane: item.id }))
+          const started = yield* Clock.currentTimeMillis
+          const result = yield* options.work(item, round).pipe(
+            Effect.map((value) => ({ ok: true as const, value })),
+            Effect.catch((error: FlowError) =>
+              Effect.succeed({ ok: false as const, error: describeFlowError(error) })
+            )
+          )
+          const ended = yield* Clock.currentTimeMillis
+          // The predicate decides, not the work's own account of itself.
+          const finished = result.ok && (yield* options.done(item))
+          const outcome = QueueOutcome.make({
+            id: item.id,
+            round,
+            status: finished ? "done" : "failed",
+            ms: ended - started,
+            at: ended,
+            ...(result.ok
+              ? {
+                  ...(finished
+                    ? {}
+                    : { note: result.value.note ?? "the work ended but left no output" }),
+                  ...(finished && result.value.note !== undefined
+                    ? { note: result.value.note }
+                    : {}),
+                  ...(result.value.confidence === undefined
+                    ? {}
+                    : { confidence: result.value.confidence }),
+                  ...(result.value.todos === undefined ? {} : { todos: result.value.todos })
+                }
+              : { note: result.error })
+          })
+          yield* record(outcome)
+          yield* options.events.publish(
+            finished
+              ? StageCompleted.make({ stage, lane: item.id })
+              : StageFailed.make({ stage, lane: item.id, message: outcome.note ?? "failed" })
+          )
+          return { item, finished }
+        }),
+      { concurrency }
+    )
+    const done = results.filter((entry) => entry.finished).map((entry) => entry.item)
+    const failed = results.filter((entry) => !entry.finished).map((entry) => entry.item)
+    if (options.afterRound !== undefined) {
+      yield* options.afterRound(round, done, failed)
+    }
+    if (done.length === 0 && failed.length > 0) {
+      return yield* Stalled.make({
+        signal: "no-progress",
+        detail: `${options.label}: round ${round} finished none of its ${failed.length} item(s)`
+      })
+    }
+    pending = failed
+  }
+  return { outcomes, rounds, pending, skipped }
+})