@llm4ts/flow 0.15.0 → 0.16.0

package/src/StoryPlan.ts

@@ -0,0 +1,353 @@
+// The epic-level plan of the parallel story executor (ADR 0013): stories
+// with a declared dependency graph and declared file ownership. Dependencies
+// are declared here, up front, never discovered by a running coder.
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PlanParseError, StoryPlanInvalid, type PersistenceError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+import { stableHash } from "./Plan.ts"
+
+export const StoryPlanVersion = 1
+
+export class Story extends Schema.Class<Story>("Story")({
+  /** Kebab-case, unique within the plan; names the branch and the worktree. */
+  id: Schema.String,
+  title: Schema.String,
+  description: Schema.String,
+  /** Story ids this one waits for; they are merged before this one starts. */
+  dependsOn: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+    Schema.withDecodingDefaultKey(Effect.succeed([]))
+  ),
+  /** Repo-relative path prefixes (files or directories) the story may create or change. */
+  owned: Schema.Array(Schema.String),
+  /** Path prefixes fed as context and forbidden to change. */
+  sharedReadOnly: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+    Schema.withDecodingDefaultKey(Effect.succeed([]))
+  ),
+  /** What dependents may rely on: routes, exports, contracts. */
+  provides: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+    Schema.withDecodingDefaultKey(Effect.succeed([]))
+  )
+}) {}
+
+export class StoryPlan extends Schema.Class<StoryPlan>("StoryPlan")({
+  epicId: Schema.String,
+  /** The epic as the operator phrased it. */
+  epic: Schema.String,
+  stories: Schema.Array(Story)
+}) {
+  story(id: string): Story | undefined {
+    return this.stories.find((story) => story.id === id)
+  }
+}
+
+/** A path prefix in canonical form: no `./`, no trailing slash, forward slashes. */
+export const normalizePath = (path: string): string =>
+  path
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^(\.\/)+/, "")
+    .replace(/\/+$/, "")
+
+/** Whether `path` is `prefix` itself or lies under it. */
+export const pathWithin = (path: string, prefix: string): boolean => {
+  const target = normalizePath(path)
+  const root = normalizePath(prefix)
+  return root.length === 0 || target === root || target.startsWith(`${root}/`)
+}
+
+const overlapping = (left: string, right: string): boolean =>
+  pathWithin(left, right) || pathWithin(right, left)
+
+/**
+ * Every violation of the plan's invariants, in one pass — an operator fixing
+ * a hand-edited plan wants the whole list, not a rerun per finding.
+ */
+export const storyPlanViolations = (plan: StoryPlan): ReadonlyArray<string> => {
+  const violations: Array<string> = []
+  const ids = new Set<string>()
+  for (const story of plan.stories) {
+    if (ids.has(story.id)) {
+      violations.push(`duplicate story id '${story.id}'`)
+    }
+    ids.add(story.id)
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(story.id)) {
+      violations.push(`story id '${story.id}' is not kebab-case`)
+    }
+    if (story.owned.length === 0) {
+      violations.push(`story '${story.id}' owns no paths`)
+    }
+    for (const dependency of story.dependsOn) {
+      if (dependency === story.id) {
+        violations.push(`story '${story.id}' depends on itself`)
+      } else if (!plan.stories.some((candidate) => candidate.id === dependency)) {
+        violations.push(`story '${story.id}' depends on unknown story '${dependency}'`)
+      }
+    }
+    for (const owned of story.owned) {
+      for (const shared of story.sharedReadOnly) {
+        if (overlapping(owned, shared)) {
+          violations.push(
+            `story '${story.id}' both owns '${owned}' and declares '${shared}' shared read-only`
+          )
+        }
+      }
+    }
+  }
+  for (let index = 0; index < plan.stories.length; index += 1) {
+    const left = plan.stories[index]
+    if (left === undefined) {
+      continue
+    }
+    for (const right of plan.stories.slice(index + 1)) {
+      for (const leftPath of left.owned) {
+        for (const rightPath of right.owned) {
+          if (overlapping(leftPath, rightPath)) {
+            violations.push(
+              `stories '${left.id}' and '${right.id}' both own '${normalizePath(leftPath)}' / '${normalizePath(rightPath)}'`
+            )
+          }
+        }
+      }
+    }
+  }
+  for (const cycle of cycles(plan)) {
+    violations.push(`dependency cycle: ${cycle.join(" -> ")}`)
+  }
+  return violations
+}
+
+const cycles = (plan: StoryPlan): ReadonlyArray<ReadonlyArray<string>> => {
+  const found: Array<ReadonlyArray<string>> = []
+  const state = new Map<string, "visiting" | "done">()
+  const visit = (id: string, trail: ReadonlyArray<string>): void => {
+    const mark = state.get(id)
+    if (mark === "done") {
+      return
+    }
+    if (mark === "visiting") {
+      const start = trail.indexOf(id)
+      found.push([...trail.slice(start), id])
+      return
+    }
+    state.set(id, "visiting")
+    for (const dependency of plan.story(id)?.dependsOn ?? []) {
+      // A self-edge is already reported as "depends on itself".
+      if (dependency !== id && plan.story(dependency) !== undefined) {
+        visit(dependency, [...trail, id])
+      }
+    }
+    state.set(id, "done")
+  }
+  for (const story of plan.stories) {
+    visit(story.id, [])
+  }
+  return found
+}
+
+export const validateStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.validate")(function* (
+  plan: StoryPlan
+): Effect.fn.Return<StoryPlan, StoryPlanInvalid> {
+  const violations = storyPlanViolations(plan)
+  return violations.length === 0 ? plan : yield* StoryPlanInvalid.make({ violations })
+})
+
+/**
+ * Stories grouped by the earliest wave they can run in (all dependencies in
+ * earlier waves). Assumes a valid plan; a cycle leaves its members out.
+ */
+export const topologicalWaves = (plan: StoryPlan): ReadonlyArray<ReadonlyArray<string>> => {
+  const waves: Array<ReadonlyArray<string>> = []
+  const placed = new Set<string>()
+  let remaining = plan.stories.map((story) => story.id)
+  while (remaining.length > 0) {
+    const wave = remaining.filter((id) =>
+      (plan.story(id)?.dependsOn ?? []).every((dependency) => placed.has(dependency))
+    )
+    if (wave.length === 0) {
+      break
+    }
+    waves.push(wave)
+    for (const id of wave) {
+      placed.add(id)
+    }
+    remaining = remaining.filter((id) => !placed.has(id))
+  }
+  return waves
+}
+
+export interface StoryProgress {
+  readonly done: ReadonlySet<string>
+  readonly failed: ReadonlySet<string>
+  readonly skipped: ReadonlySet<string>
+  readonly running: ReadonlySet<string>
+}
+
+/** Stories that may start now: not yet touched, every dependency done. Plan order. */
+export const readyStories = (plan: StoryPlan, progress: StoryProgress): ReadonlyArray<Story> =>
+  plan.stories.filter(
+    (story) =>
+      !progress.done.has(story.id) &&
+      !progress.failed.has(story.id) &&
+      !progress.skipped.has(story.id) &&
+      !progress.running.has(story.id) &&
+      story.dependsOn.every((dependency) => progress.done.has(dependency))
+  )
+
+/** Every story that transitively depends on `id`, in plan order. */
+export const dependentsOf = (plan: StoryPlan, id: string): ReadonlyArray<string> => {
+  const blocked = new Set<string>([id])
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const story of plan.stories) {
+      if (!blocked.has(story.id) && story.dependsOn.some((dependency) => blocked.has(dependency))) {
+        blocked.add(story.id)
+        grew = true
+      }
+    }
+  }
+  return plan.stories
+    .map((story) => story.id)
+    .filter((candidate) => candidate !== id && blocked.has(candidate))
+}
+
+/** Stable over the story entry's content — a changed entry means a fresh branch. */
+export const storyHash = (story: Story): string =>
+  stableHash(
+    JSON.stringify({
+      id: story.id,
+      title: story.title,
+      description: story.description,
+      dependsOn: [...story.dependsOn],
+      owned: [...story.owned].map(normalizePath),
+      sharedReadOnly: [...story.sharedReadOnly].map(normalizePath),
+      provides: [...story.provides]
+    })
+  )
+
+export const storyPlanFenceInfo = "json storyplan"
+
+const fencePattern = /```json[ \t]+storyplan[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*```/
+
+/** The raw JSON of the first ```json storyplan fenced block, if any. */
+export const storyPlanBlock = (markdown: string): string | undefined =>
+  fencePattern.exec(markdown)?.[1]
+
+/**
+ * Decodes the story plan embedded in its markdown file. Decoding only —
+ * `validateStoryPlan` checks the graph invariants separately, so a parse
+ * failure and an invalid plan are told apart.
+ */
+export const parseStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.parse")(function* (
+  markdown: string
+): Effect.fn.Return<StoryPlan, PlanParseError> {
+  const block = storyPlanBlock(markdown)
+  if (block === undefined) {
+    return yield* PlanParseError.make({
+      message: "no ```json storyplan fenced block in the story plan markdown"
+    })
+  }
+  return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(StoryPlan))(block).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({ message: `invalid story plan block: ${String(error)}` })
+    )
+  )
+})
+
+const list = (items: ReadonlyArray<string>): string =>
+  items.length === 0 ? "none" : items.join(", ")
+
+/**
+ * The operator-facing markdown: a readable summary per story plus the
+ * fenced block that is the source of truth. Editing the block and rerunning
+ * is the approval and the re-plan path.
+ */
+export const renderStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.render")(function* (
+  plan: StoryPlan
+): Effect.fn.Return<string, PlanParseError> {
+  const encoded = yield* Schema.encodeEffect(StoryPlan)(plan).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({ message: `story plan not encodable: ${String(error)}` })
+    )
+  )
+  const waves = topologicalWaves(plan)
+  const lines: Array<string> = [
+    `# Epic: ${plan.epicId}`,
+    "",
+    plan.epic.trim(),
+    "",
+    "## Waves",
+    "",
+    ...waves.map((wave, index) => `${index + 1}. ${wave.join(", ")}`),
+    "",
+    "## Stories",
+    ""
+  ]
+  for (const story of plan.stories) {
+    lines.push(
+      `### ${story.id} — ${story.title}`,
+      "",
+      story.description.trim(),
+      "",
+      `- depends on: ${list(story.dependsOn)}`,
+      `- owned: ${list(story.owned)}`,
+      `- shared read-only: ${list(story.sharedReadOnly)}`,
+      `- provides: ${list(story.provides)}`,
+      ""
+    )
+  }
+  lines.push(
+    "## Plan block",
+    "",
+    "Edit this block to change the plan; the prose above is regenerated from it.",
+    "",
+    "```" + storyPlanFenceInfo,
+    JSON.stringify(encoded, null, 2),
+    "```",
+    ""
+  )
+  return lines.join("\n")
+})
+
+export interface StoryPlanStoreShape {
+  readonly save: (
+    path: string,
+    plan: StoryPlan
+  ) => Effect.Effect<void, PersistenceError | PlanParseError>
+  readonly load: (
+    path: string
+  ) => Effect.Effect<StoryPlan | undefined, PersistenceError | PlanParseError>
+  /** An existing file wins over `create`: the operator's edits are the plan. */
+  readonly recoverOrCreate: <E, R>(
+    path: string,
+    create: Effect.Effect<StoryPlan, E, R>
+  ) => Effect.Effect<StoryPlan, E | PersistenceError | PlanParseError, R>
+}
+
+export const makeStoryPlanStore = (files: PlainFileStoreShape): StoryPlanStoreShape => {
+  const save = (
+    path: string,
+    plan: StoryPlan
+  ): Effect.Effect<void, PersistenceError | PlanParseError> =>
+    Effect.flatMap(renderStoryPlan(plan), (markdown) => files.writeAtomic(path, markdown))
+  const load = (
+    path: string
+  ): Effect.Effect<StoryPlan | undefined, PersistenceError | PlanParseError> =>
+    Effect.flatMap(files.read(path), (contents) =>
+      contents === undefined ? Effect.succeed(undefined) : parseStoryPlan(contents)
+    )
+  return {
+    save,
+    load,
+    recoverOrCreate: (path, create) =>
+      Effect.flatMap(load(path), (stored) =>
+        stored === undefined
+          ? Effect.tap(create, (plan) => save(path, plan))
+          : Effect.succeed(stored)
+      )
+  }
+}

package/src/TransientRetry.ts

@@ -119,6 +119,14 @@ export interface TransientRetryOptions {
   readonly baseDelay?: Duration.Input
   readonly flakyRetries?: number
   readonly flakyDelay?: Duration.Input
+  /**
+   * Re-asks a structured call whose response could not be parsed as the
+   * requested JSON, with the parse failure quoted back to the model. The
+   * model's output is not deterministic, so a malformed or off-schema reply
+   * is usually a one-off; but a schema the model cannot satisfy fails every
+   * time, so this budget is small (default 2) and independent of the others.
+   */
+  readonly parseRetries?: number
 }
 
 interface ResolvedTransientRetryOptions {
@@ -126,15 +134,43 @@ interface ResolvedTransientRetryOptions {
   readonly baseDelay: Duration.Duration
   readonly flakyRetries: number
   readonly flakyDelay: Duration.Duration
+  readonly parseRetries: number
 }
 
 const resolveOptions = (options: TransientRetryOptions): ResolvedTransientRetryOptions => ({
   maxRetries: options.maxRetries ?? 3,
   baseDelay: Duration.fromInputUnsafe(options.baseDelay ?? "1 second"),
   flakyRetries: options.flakyRetries ?? 6,
-  flakyDelay: Duration.fromInputUnsafe(options.flakyDelay ?? "1 second")
+  flakyDelay: Duration.fromInputUnsafe(options.flakyDelay ?? "1 second"),
+  parseRetries: options.parseRetries ?? 2
 })
 
+/** A structured call whose text came back but did not decode as the requested JSON. */
+export const isStructuredParseFailure = (error: LlmError): boolean => error._tag === "ParseError"
+
+const repairReasonLimit = 400
+
+/**
+ * The prompt for a structured re-ask: the original, plus what went wrong
+ * with the previous reply. Quoting the failure is what turns a blind retry
+ * into a repair — the common causes (prose around the JSON, a missing
+ * required field, a string where a number was asked for) are all things the
+ * model fixes on sight.
+ */
+export const repairPrompt = (prompt: string, error: LlmError): string => {
+  const reason = error.message.trim()
+  const shown =
+    reason.length <= repairReasonLimit ? reason : `${reason.slice(0, repairReasonLimit - 3)}...`
+  return [
+    prompt,
+    "",
+    "Your previous reply could not be parsed as the requested JSON:",
+    shown,
+    "Reply again with ONLY the JSON object — no prose before or after it, no markdown",
+    "fences, every required field present, and values of the requested types."
+  ].join("\n")
+}
+
 const backoff = (baseDelay: Duration.Duration, attempt: number): Duration.Duration =>
   Duration.times(baseDelay, 2 ** attempt)
 
@@ -256,6 +292,39 @@ const retryStream = <R>(
   return loop(0, 0)
 }
 
+/**
+ * A structured call under all three budgets: `run(prompt)` is retried for
+ * transient and flaky failures as any effect is, and a parse failure re-asks
+ * with `repairPrompt` up to `parseRetries` times before it is surfaced.
+ */
+const retryStructured = <A, R>(
+  prompt: string,
+  run: (prompt: string) => Effect.Effect<A, LlmError, R>,
+  options: ResolvedTransientRetryOptions,
+  events: FlowEvents["Service"]
+): Effect.Effect<A, LlmError, R> => {
+  const loop = (current: string, parseAttempt: number): Effect.Effect<A, LlmError, R> =>
+    retryEffect(run(current), "structured", options, events).pipe(
+      Effect.catchIf(
+        (error) => isStructuredParseFailure(error) && parseAttempt < options.parseRetries,
+        (error) =>
+          waitForRetry(
+            events,
+            "structured output (repair retry)",
+            parseAttempt,
+            options.parseRetries,
+            error,
+            options.flakyDelay
+          ).pipe(
+            Effect.andThen(
+              Effect.suspend(() => loop(repairPrompt(prompt, error), parseAttempt + 1))
+            )
+          )
+      )
+    )
+  return loop(prompt, 0)
+}
+
 export const makeTransientRetry = Effect.fn("@llm4ts/flow/TransientRetry.make")(function* (
   underlying: LlmServiceShape,
   retryOptions: TransientRetryOptions = {}
@@ -271,16 +340,16 @@ export const makeTransientRetry = Effect.fn("@llm4ts/flow/TransientRetry.make")(
     executeWithTools: (prompt, tools) =>
       retryEffect(underlying.executeWithTools(prompt, tools), "tools", options, events),
     executeStructured: (prompt, schema, jsonSchema) =>
-      retryEffect(
-        underlying.executeStructured(prompt, schema, jsonSchema),
-        "structured",
+      retryStructured(
+        prompt,
+        (current) => underlying.executeStructured(current, schema, jsonSchema),
         options,
         events
       ),
     executeStructuredWithUsage: (prompt, schema, jsonSchema) =>
-      retryEffect(
-        underlying.executeStructuredWithUsage(prompt, schema, jsonSchema),
-        "structured",
+      retryStructured(
+        prompt,
+        (current) => underlying.executeStructuredWithUsage(current, schema, jsonSchema),
         options,
         events
       ),