@llm4ts/flow 2.41.0 → 2.42.0

package/src/FlowContext.ts

@@ -16,6 +16,11 @@ export interface ContextOptions {
   readonly prefer?: string
   /** Who the context is for, in the roster's events ("story conto-overview"). */
   readonly label?: string
+  /**
+   * Take a coder only if one is free now, else fail `RosterExhausted` at
+   * once: a task offered aside never waits for a slot (ADR 0034).
+   */
+  readonly ifFree?: boolean
 }
 
 export interface FlowContextShape {

package/src/FlowEvents.ts

@@ -295,6 +295,10 @@ export class TaskStarted extends Schema.TaggedClass<TaskStarted>()("TaskStarted"
   count: Schema.Int,
   title: Schema.String,
   satisfies: Schema.optionalKey(Schema.Array(Schema.Int)),
+  /** The task runs beside the story's held coder, in its own worktree (ADR 0034). */
+  parallel: Schema.optionalKey(Schema.Boolean),
+  /** The clone of the extra coder a parallel task holds (ADR 0034). */
+  clone: Schema.optionalKey(Schema.Int),
   lane: Schema.optionalKey(Schema.String),
   executor: Schema.optionalKey(Schema.String)
 }) {}
@@ -513,7 +517,11 @@ const stamped = (
             count: event.count,
             title: event.title,
             ...(event.satisfies === undefined ? {} : { satisfies: event.satisfies }),
-            ...tags
+            ...tags,
+            // A parallel task names its own coder, not the lane's (ADR 0034).
+            ...(event.parallel === undefined ? {} : { parallel: event.parallel }),
+            ...(event.executor === undefined ? {} : { executor: event.executor }),
+            ...(event.clone === undefined ? {} : { clone: event.clone })
           })
     case "TaskCompleted":
       return event.lane !== undefined

package/src/Perimeter.ts

@@ -131,3 +131,39 @@ export const strayTasks = (
     })
     return [{ task, paths, foreign }]
   })
+
+/** A task's `Owns:` entry as a path prefix: `src/session/*` and `src/routes/**` own their directory. */
+const ownedPrefix = (entry: string): string => entry.replace(/\/?\*+$/u, "")
+
+/**
+ * A task run aside (ADR 0034) as a gate over what it changed: every path
+ * outside its `Owns:` entries is one Critical issue handed back to its
+ * coder, so two tasks running at once keep to their own files. A task that
+ * names no paths is not checked; the story's perimeter still is.
+ */
+export const taskOwnsGate = (
+  changedPaths: ReadonlyArray<string>,
+  owns: ReadonlyArray<string>
+): ReviewResult => {
+  if (owns.length === 0) {
+    return ReviewResult.make({ issues: [], summary: "" })
+  }
+  const prefixes = owns.map(ownedPrefix)
+  const stray = changedPaths.filter((path) => !prefixes.some((prefix) => pathWithin(path, prefix)))
+  return stray.length === 0
+    ? ReviewResult.make({ issues: [], summary: "task owns: clean" })
+    : ReviewResult.make({
+        issues: [
+          ReviewIssue.make({
+            severity: "Critical",
+            title: "task owns",
+            description: [
+              `This task owns ${owns.join(", ")} and changed paths outside them: ${stray.join(", ")}.`,
+              "Another task may be changing those right now. Revert them and keep this task's",
+              "work inside the paths it owns."
+            ].join("\n")
+          })
+        ],
+        summary: "task owns: violated"
+      })
+}

package/src/Plan.ts

@@ -120,3 +120,74 @@ export const parsePlan = Effect.fn("@llm4ts/flow/Plan.parse")(function* (
     ...(brief === undefined ? {} : { brief })
   })
 })
+
+// ---- The task graph (ADR 0034) ------------------------------------------------
+
+/**
+ * The tasks a task waits for, from its description's `Depends on:` line
+ * (`1, 3`, or `none`). Without the line it waits for every earlier task, so
+ * a plan written before ADR 0034 runs in order. Only earlier tasks count: a
+ * forward or self reference is dropped, so the graph never has a cycle, and
+ * a line left naming none of them is read as no line.
+ */
+export const dependsOnOf = (description: string, index: number): ReadonlyArray<number> => {
+  const earlier = Array.from({ length: Math.max(0, index - 1) }, (_, position) => position + 1)
+  const match = /\bDepends on:\s*([^\n.]*)/iu.exec(description)
+  if (match === null) {
+    return earlier
+  }
+  const text = match[1] ?? ""
+  if (/^\s*none\b/iu.test(text)) {
+    return []
+  }
+  const named = [
+    ...new Set(
+      text
+        .split(/[^\d]+/u)
+        .filter((part) => part.length > 0)
+        .map((part) => Number.parseInt(part, 10))
+        .filter((number) => Number.isInteger(number) && number >= 1 && number < index)
+    )
+  ]
+  return named.length === 0 ? earlier : named
+}
+
+/**
+ * The paths a task says it changes, from its `Owns:` line; empty when it
+ * says none. The line ends at a newline, the next label, or a period that
+ * ends the sentence (the planner writes one-line JSON descriptions).
+ */
+export const ownsOf = (description: string): ReadonlyArray<string> => {
+  const match = /\bOwns:\s*(.*?)(?=\s+(?:Depends on|Satisfies):|\.\s|\.$|\n|$)/iu.exec(description)
+  return match === null
+    ? []
+    : (match[1] ?? "")
+        .split(/[,\s]+/u)
+        .map((path) =>
+          path
+            .trim()
+            .replace(/^`|`$/gu, "")
+            .replace(/[.;]+$/u, "")
+        )
+        .filter((path) => path.length > 0 && path.toLowerCase() !== "none")
+}
+
+/** One task of a plan as the scheduler sees it: its 1-based index and what it waits for. */
+export interface TaskNode {
+  readonly index: number
+  readonly task: Task
+  readonly dependsOn: ReadonlyArray<number>
+  readonly owns: ReadonlyArray<string>
+}
+
+export const taskGraph = (plan: Plan): ReadonlyArray<TaskNode> =>
+  plan.tasks.map((task, position) => ({
+    index: position + 1,
+    task,
+    dependsOn: dependsOnOf(task.description, position + 1),
+    owns: ownsOf(task.description)
+  }))
+
+/** Whether some task of the plan may start without the task right before it. */
+export const hasParallelTasks = (plan: Plan): boolean =>
+  taskGraph(plan).some((node) => node.index > 1 && !node.dependsOn.includes(node.index - 1))

package/src/PlanExecution.ts

@@ -1,4 +1,8 @@
 import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Fiber from "effect/Fiber"
+import * as Queue from "effect/Queue"
+import * as Semaphore from "effect/Semaphore"
 import {
   StageCompleted,
   StageFailed,
@@ -9,8 +13,8 @@ import {
   type FlowEventsShape
 } from "./FlowEvents.ts"
 import { withKindSpan, type SpanOptions } from "./Spans.ts"
-import { describeFlowError, type FlowError } from "./FlowError.ts"
-import type { Plan, Task } from "./Plan.ts"
+import { FlowAborted, describeFlowError, type FlowError } from "./FlowError.ts"
+import { taskGraph, type Plan, type Task, type TaskNode } from "./Plan.ts"
 import type { PlanStoreShape } from "./Persistence.ts"
 
 const errorMessage = describeFlowError
@@ -97,3 +101,185 @@ export const implementTaskLoop = Effect.fn("@llm4ts/flow/PlanExecution.implement
     return current
   }
 )
+
+// ---- Tasks beside the held coder (ADR 0034) -----------------------------------
+
+/**
+ * How a task tried beside the held coder ended: `merged` into the story,
+ * `declined` (no free coder, or it could not finish there) or `conflict`
+ * (its merge back conflicted). The last two go back to the held coder; a
+ * conflicting task runs after the others, on the merged state.
+ */
+export type AsideOutcome = "merged" | "declined" | "conflict"
+
+export interface AsideRequest {
+  readonly node: TaskNode
+  /** The plan's size, for `task n/m`. */
+  readonly count: number
+  readonly planSoFar: Plan
+  /** Runs `effect` while no task runs at home: the merge back into the story. */
+  readonly exclusive: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /** Says the task started, on the coder it got; call it once that coder is held. */
+  readonly announce: (coder: {
+    readonly executor?: string
+    readonly clone?: number
+  }) => Effect.Effect<void>
+}
+
+export interface ParallelTasks<E, R> {
+  /** Coders one story may hold at once, its own included; 1 runs every task at home. */
+  readonly concurrency: number
+  readonly aside: (request: AsideRequest) => Effect.Effect<AsideOutcome, E, R>
+}
+
+/** A task's run that ended: at home (`undefined`) or aside (its outcome). */
+interface Finished<E> {
+  readonly kind: "home" | "aside"
+  readonly node: TaskNode
+  readonly exit: Exit.Exit<AsideOutcome | undefined, E>
+}
+
+/**
+ * The task loop over the plan's graph (ADR 0034): the held coder runs one
+ * ready task at a time, in plan order, as `implementTaskLoop` does; up to
+ * `concurrency - 1` other ready tasks are offered to `aside`, which runs
+ * each on another coder and merges it back under `exclusive`. A task is
+ * ready when the tasks it depends on are complete; a plan whose every task
+ * depends on the one before runs exactly as `implementTaskLoop`.
+ */
+export const implementTaskGraph = Effect.fn("@llm4ts/flow/PlanExecution.implementTaskGraph")(
+  function* <E, R, E2, R2>(
+    store: PlanStoreShape,
+    events: FlowEventsShape,
+    planPath: string,
+    plan: Plan,
+    perTask: (task: Task, planSoFar: Plan) => Effect.Effect<void, E, R>,
+    parallel: ParallelTasks<E2, R2>
+  ): Effect.fn.Return<Plan, E | E2 | FlowError, R | R2> {
+    const graph = taskGraph(plan)
+    const count = graph.length
+    yield* events.publish(
+      TasksPlanned.make({
+        tasks: plan.tasks.map((task) => ({
+          title: task.title,
+          completed: task.completed,
+          ...withSatisfies(task.description)
+        }))
+      })
+    )
+    let current = plan
+    const done = new Set(graph.filter((node) => node.task.completed).map((node) => node.index))
+    /** Tasks that go to the held coder only, and those that wait for every other one. */
+    const homeOnly = new Set<number>()
+    const last = new Set<number>()
+    const running = new Map<number, "home" | "aside">()
+    const fibers: Array<Fiber.Fiber<unknown, unknown>> = []
+    const finished = yield* Queue.unbounded<Finished<E | E2>>()
+    const home = yield* Semaphore.make(1)
+    const exclusive = <A, EX, RX>(effect: Effect.Effect<A, EX, RX>) => home.withPermit(effect)
+
+    const started = (
+      node: TaskNode,
+      extra: Partial<Pick<TaskStarted, "parallel" | "executor" | "clone">> = {}
+    ) =>
+      events.publish(
+        TaskStarted.make({
+          index: node.index,
+          count,
+          title: node.task.title,
+          ...withSatisfies(node.task.description),
+          ...extra
+        })
+      )
+    const complete = (node: TaskNode) =>
+      Effect.gen(function* () {
+        current = current.complete(node.task.title)
+        yield* store.save(planPath, current)
+        done.add(node.index)
+        yield* events.publish(
+          TaskCompleted.make({ index: node.index, count, title: node.task.title })
+        )
+      })
+
+    while (done.size < count) {
+      const ready = graph.filter(
+        (node) =>
+          !done.has(node.index) &&
+          !running.has(node.index) &&
+          node.dependsOn.every((index) => done.has(index))
+      )
+      if (![...running.values()].includes("home")) {
+        const pick = ready.find((node) => !last.has(node.index)) ?? ready[0]
+        if (pick !== undefined) {
+          running.set(pick.index, "home")
+          const snapshot = current
+          fibers.push(
+            yield* Effect.forkChild(
+              exclusive(
+                Effect.andThen(
+                  started(pick),
+                  stage(events, pick.task.title, perTask(pick.task, snapshot))
+                )
+              ).pipe(
+                Effect.as(undefined),
+                Effect.exit,
+                Effect.flatMap((exit) => Queue.offer(finished, { kind: "home", node: pick, exit }))
+              )
+            )
+          )
+        }
+      }
+      for (const node of ready) {
+        if (running.size >= parallel.concurrency) {
+          break
+        }
+        if (running.has(node.index) || homeOnly.has(node.index)) {
+          continue
+        }
+        running.set(node.index, "aside")
+        const request: AsideRequest = {
+          node,
+          count,
+          planSoFar: current,
+          exclusive,
+          announce: (coder) =>
+            started(node, {
+              parallel: true,
+              ...(coder.executor === undefined ? {} : { executor: coder.executor }),
+              ...(coder.clone === undefined ? {} : { clone: coder.clone })
+            })
+        }
+        fibers.push(
+          yield* Effect.forkChild(
+            parallel.aside(request).pipe(
+              Effect.exit,
+              Effect.flatMap((exit) => Queue.offer(finished, { kind: "aside", node, exit }))
+            )
+          )
+        )
+      }
+      if (running.size === 0) {
+        return yield* FlowAborted.make({
+          message: `plan ${plan.epicId}: no task can start, though ${count - done.size} are not done`
+        })
+      }
+      const next = yield* Queue.take(finished)
+      running.delete(next.node.index)
+      if (Exit.isFailure(next.exit)) {
+        yield* Fiber.interruptAll(fibers)
+        return yield* Effect.failCause(next.exit.cause)
+      }
+      if (next.kind === "home") {
+        yield* complete(next.node)
+      } else if (next.exit.value === "merged") {
+        yield* complete(next.node)
+      } else {
+        homeOnly.add(next.node.index)
+        if (next.exit.value === "conflict") {
+          last.add(next.node.index)
+        }
+      }
+    }
+    return current
+  }
+)

package/src/RosterSeats.ts

@@ -11,7 +11,7 @@ import * as Stream from "effect/Stream"
 import { ConfigError, type LlmError } from "@llm4ts/core/Errors"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { Message, type ConnectorCapabilities, type LlmChunk } from "@llm4ts/core/Models"
-import { describeFlowError, type FlowError } from "./FlowError.ts"
+import { describeFlowError, type FlowError, RosterExhausted } from "./FlowError.ts"
 import { ExecutorHandedOver, type FlowEventsShape } from "./FlowEvents.ts"
 import { callPurpose } from "./Timing.ts"
 import {
@@ -48,6 +48,8 @@ export interface RosterView {
   readonly capacityChanged: (role: Role, from: number) => Effect.Effect<number>
   /** The executor holding this context's coder, once leased. */
   readonly executor: Effect.Effect<string | undefined>
+  /** Which clone of it (ADR 0033), once leased. */
+  readonly clone?: Effect.Effect<number | undefined>
   /** Every executor that held this context's coder, in order (handovers). */
   readonly history: Effect.Effect<ReadonlyArray<string>>
   /** The autonomy contract profile an executor's roster entry asks for (ADR 0027), when it does. */
@@ -253,6 +255,11 @@ export interface HeldCoderOptions {
   /** Handovers before a failure surfaces. Default 2. */
   readonly maxHandovers?: number
   readonly label?: string
+  /**
+   * Lease only a slot that is free now; none fails `RosterExhausted` at
+   * once instead of waiting (a task run aside, ADR 0034).
+   */
+  readonly ifFree?: boolean
 }
 
 export interface HeldCoder {
@@ -305,12 +312,26 @@ export const makeHeldCoder = Effect.fn("@llm4ts/flow/RosterSeats.heldCoder")(fun
         return held
       }
       const preferred = yield* Ref.get(prefer)
-      const lease = yield* roster
-        .lease("coder", {
-          ...(preferred === undefined ? {} : { prefer: preferred }),
-          ...(options.label === undefined ? {} : { label: options.label })
-        })
-        .pipe(Scope.provide(scope))
+      const leaseOptions = {
+        ...(preferred === undefined ? {} : { prefer: preferred }),
+        ...(options.label === undefined ? {} : { label: options.label })
+      }
+      const lease =
+        options.ifFree === true
+          ? yield* roster.tryLease("coder", leaseOptions).pipe(
+              Scope.provide(scope),
+              Effect.flatMap((free) =>
+                free === undefined
+                  ? Effect.fail(
+                      RosterExhausted.make({
+                        role: "coder",
+                        reasons: ["no coder slot is free now"]
+                      })
+                    )
+                  : Effect.succeed(free)
+              )
+            )
+          : yield* roster.lease("coder", leaseOptions).pipe(Scope.provide(scope))
       const seat = yield* source.seatFor(lease.executor, "coder", workDir)
       const next = { lease, seat }
       yield* Ref.set(current, next)