@llm4ts/flow 0.9.1 → 0.11.0

package/src/Context.ts

@@ -0,0 +1,207 @@
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import { FlowLlmError, type FlowError } from "./FlowError.ts"
+import { FlowEvents, Info } from "./FlowEvents.ts"
+import { isContextOverflow, isContextOverflowMessage } from "./TransientRetry.ts"
+
+// Context budgeting for LLM prompts: bound what a call ships, and make every
+// truncation visible. Budgets are in CHARACTERS, not tokens — deterministic, no
+// tokenizer dependency. Rule of thumb ~3.5 chars/token for code, so the 400k
+// default is ~115k tokens: conservative against every provider.
+
+const marker = "\n\n… [truncated] …\n\n"
+
+export interface CappedText {
+  readonly text: string
+  readonly originalChars: number
+  readonly truncated: boolean
+}
+
+/**
+ * Bound `text` to `limit` characters — the result is NEVER longer than `limit`,
+ * marker included. Keeps the head (3/4 of the remaining room) and the tail (1/4)
+ * so both the entry points and the trailing rules survive; the middle is where
+ * boilerplate lives. For `limit <= 0` the closest achievable result is the
+ * empty string, since length can't go negative.
+ */
+export const cap = (text: string, limit: number): CappedText => {
+  if (text.length <= limit) {
+    return { text, originalChars: text.length, truncated: false }
+  }
+  if (limit <= marker.length) {
+    return { text: text.slice(0, Math.max(limit, 0)), originalChars: text.length, truncated: true }
+  }
+  const room = limit - marker.length
+  const head = Math.floor((room * 3) / 4)
+  const tail = room - head
+  return {
+    text: `${text.slice(0, head)}${marker}${text.slice(text.length - tail)}`,
+    originalChars: text.length,
+    truncated: true
+  }
+}
+
+export const defaultContextBudget = 400_000
+
+/**
+ * The default character budget: `LLM4TS_CONTEXT_BUDGET`, else the deprecated
+ * `LLM4TS_JUDGE_SOURCES_LIMIT`, else 400_000.
+ */
+export const budget = (
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): number => {
+  const raw = environment["LLM4TS_CONTEXT_BUDGET"] ?? environment["LLM4TS_JUDGE_SOURCES_LIMIT"]
+  if (raw === undefined) {
+    return defaultContextBudget
+  }
+  const parsed = Number.parseInt(raw.trim(), 10)
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultContextBudget
+}
+
+/**
+ * Which kind of shrinking produced a truncation — the two are NOT
+ * interchangeable. "capped" numbers are literal character counts of shortened
+ * text; "shrunk" numbers are attempted budget CEILINGS after an oversized
+ * prompt failed. Conflating them would misreport how much content a
+ * clean-room audit actually lost.
+ */
+export type TruncationKind = "capped" | "shrunk"
+
+export interface Truncation {
+  readonly label: string
+  readonly originalChars: number
+  readonly keptChars: number
+  readonly kind: TruncationKind
+}
+
+export const renderTruncation = (truncation: Truncation): string =>
+  truncation.kind === "capped"
+    ? `${truncation.label}: truncated ${truncation.originalChars} → ${truncation.keptChars} chars`
+    : `${truncation.label}: retried at a lower budget, ${truncation.originalChars} → ${truncation.keptChars} chars (ceilings, not text size)`
+
+// The ambient truncation log, written only by `capped` and `withShrink` so no
+// call site can truncate without recording. The Reference default is a single
+// process-wide cell; `isolateTruncations` scopes a fresh one so concurrent
+// flows don't cross-contaminate and a phase reads back exactly what its own
+// calls truncated.
+const CurrentTruncations = Context.Reference<Ref.Ref<ReadonlyArray<Truncation>>>(
+  "@llm4ts/flow/Context/CurrentTruncations",
+  { defaultValue: () => Ref.makeUnsafe<ReadonlyArray<Truncation>>([]) }
+)
+
+const record = (truncation: Truncation): Effect.Effect<void> =>
+  Effect.flatMap(Effect.service(CurrentTruncations), (log) =>
+    Ref.update(log, (recorded) => [...recorded, truncation])
+  )
+
+/** Truncations recorded so far. Phases write these into `provenance.json`. */
+export const truncations: Effect.Effect<ReadonlyArray<Truncation>> = Effect.flatMap(
+  Effect.service(CurrentTruncations),
+  Ref.get
+)
+
+/** Run `effect` against a fresh, private truncation log. */
+export const isolateTruncations = <A, E, R>(
+  effect: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, R> =>
+  Effect.flatMap(Ref.make<ReadonlyArray<Truncation>>([]), (fresh) =>
+    Effect.provideService(effect, CurrentTruncations, fresh)
+  )
+
+/**
+ * `cap`, publishing a `FlowEvent` and recording the truncation when one
+ * happens. `label` names what was shortened, so the event and the provenance
+ * entry are readable ("specs", "branch diff", "judge context").
+ */
+export const capped = Effect.fn("@llm4ts/flow/Context.capped")(function* (
+  label: string,
+  text: string,
+  limit: number
+): Effect.fn.Return<string, never, FlowEvents> {
+  const out = cap(text, limit)
+  if (!out.truncated) {
+    return out.text
+  }
+  const events = yield* FlowEvents
+  yield* events.publish(
+    Info.make({
+      message: `⚠ context: ${label} truncated ${out.originalChars} → ${out.text.length} chars`
+    })
+  )
+  yield* record({
+    label,
+    originalChars: out.originalChars,
+    keptChars: out.text.length,
+    kind: "capped"
+  })
+  return out.text
+})
+
+// True for the two failure classes a smaller prompt can fix: a deterministic
+// context overflow, and the empty response gemini returns when a prompt is too
+// large for it to even start. The overflow check delegates to TransientRetry's
+// phrasing list so a message-only failure (no surviving typed LlmError) is
+// still caught — a second, shorter copy here would drift.
+const shrinkable = (error: FlowError): boolean =>
+  error._tag === "Llm" &&
+  ((error.cause !== undefined && isContextOverflow(error.cause)) ||
+    isContextOverflowMessage(error.message) ||
+    error.message.toLowerCase().includes("empty response"))
+
+export interface WithShrinkOptions {
+  readonly start?: number
+  readonly environment?: Readonly<Record<string, string | undefined>>
+}
+
+/**
+ * Run `f` at `start` characters (default: `budget()`); on a shrinkable failure
+ * retry at 1/2, then 1/4, then give up. Repeating the same oversized prompt
+ * cannot succeed, so shrinking is the only retry that makes sense for this
+ * failure class — which is why context overflow is deliberately excluded from
+ * `TransientRetry`'s budget. Each shrink publishes a `FlowEvent` and is
+ * recorded like any other truncation. The terminal failure deliberately drops
+ * the typed cause: a resume layer classifying an "empty response" cause as
+ * flaky would replay this exact, permanently-failing budget sequence forever.
+ */
+export const withShrink = <A, E extends FlowError, R>(
+  label: string,
+  f: (chars: number) => Effect.Effect<A, E, R>,
+  options: WithShrinkOptions = {}
+): Effect.Effect<A, E | FlowLlmError, R | FlowEvents> => {
+  const start = options.start ?? budget(options.environment)
+  const attempt = (
+    atChars: number,
+    rest: ReadonlyArray<number>
+  ): Effect.Effect<A, E | FlowLlmError, R | FlowEvents> =>
+    Effect.catchIf(
+      f(atChars),
+      () => true,
+      (error): Effect.Effect<A, E | FlowLlmError, R | FlowEvents> => {
+        if (!shrinkable(error)) {
+          return Effect.fail(error)
+        }
+        if (rest.length === 0) {
+          return Effect.fail(
+            FlowLlmError.make({
+              message:
+                `${label} exceeded the model's input limit even after shrinking to ${atChars} chars — ` +
+                `lower LLM4TS_CONTEXT_BUDGET or scope this phase further (cause: ${error.message})`
+            })
+          )
+        }
+        const [next, ...remaining] = rest
+        return Effect.gen(function* () {
+          const events = yield* FlowEvents
+          yield* events.publish(
+            Info.make({
+              message: `⚠ context: ${label} did not fit at ${atChars} chars — shrinking to ${next}: ${error.message}`
+            })
+          )
+          yield* record({ label, originalChars: atChars, keptChars: next, kind: "shrunk" })
+          return yield* attempt(next, remaining)
+        })
+      }
+    )
+  return attempt(start, [Math.floor(start / 2), Math.floor(start / 4)])
+}

package/src/GitTool.ts

@@ -29,6 +29,11 @@ export interface GitToolShape {
   readonly diffAll: Effect.Effect<string, FlowError>
   readonly defaultBase: Effect.Effect<string, FlowError>
   readonly diffVsBase: (base: string, threeDot?: boolean) => Effect.Effect<string, FlowError>
+  readonly diffVsBaseScoped: (
+    base: string,
+    paths: ReadonlyArray<string>,
+    threeDot?: boolean
+  ) => Effect.Effect<string, FlowError>
   readonly changedFilesVsBase: (
     base: string,
     threeDot?: boolean
@@ -206,6 +211,22 @@ export const makeGitTool = (
     defaultBase: read("git defaultBase", defaultBaseEffect),
     diffVsBase: (base, threeDot = true) =>
       read("git diffVsBase", runOrFail(["diff", `${base}${threeDot ? "..." : ".."}HEAD`])),
+    // Diff vs base restricted to paths — the per-program / per-lens scoping
+    // primitive. An EMPTY paths list returns the empty string rather than the
+    // whole diff: bare `git diff <range> --` means "everything", which would
+    // silently defeat every caller that scopes by a computed, possibly-empty
+    // file set. The empty check lives INSIDE read(...), not before it — a
+    // pre-guard early return would let diffVsBaseScoped(base, []) silently
+    // succeed under grants that deny GitRead, with no CapabilityDenied audit.
+    diffVsBaseScoped: (base, paths, threeDot = true) =>
+      read(
+        "git diffVsBase (scoped)",
+        Effect.suspend(() =>
+          paths.length === 0
+            ? Effect.succeed("")
+            : runOrFail(["diff", `${base}${threeDot ? "..." : ".."}HEAD`, "--", ...paths])
+        )
+      ),
     changedFilesVsBase: (base, threeDot = true) =>
       read(
         "git changedFilesVsBase",

package/src/Pack.ts

@@ -33,9 +33,17 @@ export interface Pack {
   readonly prompts: Readonly<Record<string, string>>
   readonly lenses: ReadonlyArray<Reviewer>
   readonly lessons: string | undefined
+  // Regex template locating a program's TARGET implementation files (relative
+  // paths), `<NAME>` substituted with the program name. The seam that makes
+  // per-program judging possible.
+  readonly programFiles: string | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
+  // The regex for `program`'s implementation files: the `programFiles:`
+  // template with `<NAME>` substituted, or a case-insensitive "path contains
+  // the program name" fallback.
+  readonly filesFor: (program: string) => RegExp
 }
 
 interface ParsedManifest {
@@ -134,6 +142,17 @@ const dimensions = (body: string | undefined): ReadonlyArray<Dimension> =>
       : [Dimension.make({ name, rubric, maxScore })]
   })
 
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+const isValidRegExp = (source: string): boolean => {
+  try {
+    new RegExp(source)
+    return true
+  } catch {
+    return false
+  }
+}
+
 const markdownSidecars = Effect.fn("@llm4ts/flow/Pack.markdownSidecars")(function* (
   workspace: WorkspaceShape,
   directory: string
@@ -173,6 +192,16 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, text]) => parseReviewer(name, text))
   const fields = manifest.fields
+  const programFiles = fields["programFiles"]
+  // Validated at load so a mis-typed template fails the pack, not a later
+  // phase; substitution cannot introduce invalid syntax because the fallback
+  // probe uses an alphanumeric stand-in and real substitutions are escaped
+  // only in the no-template fallback, mirroring the reference behavior.
+  if (programFiles !== undefined && !isValidRegExp(programFiles.replaceAll("<NAME>", "PROBE"))) {
+    return yield* PlanParseError.make({
+      message: `pack manifest 'programFiles:' is not a valid regex template: ${programFiles}`
+    })
+  }
   const pack: Pack = {
     name: manifest.name,
     source: fields.source ?? "",
@@ -198,9 +227,16 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     prompts,
     lenses,
     lessons: lessons === undefined || lessons.length === 0 ? undefined : lessons,
+    programFiles,
     dir: directory,
     gate: (name) => gates[name],
-    prompt: (name) => prompts[name]
+    prompt: (name) => prompts[name],
+    // The template is anchored to the whole path (the reference full-matches);
+    // the fallback is a deliberate substring "path contains the name" match.
+    filesFor: (program) =>
+      programFiles === undefined
+        ? new RegExp(escapeRegExp(program), "i")
+        : new RegExp(`^(?:${programFiles.replaceAll("<NAME>", program)})$`)
   }
   return pack
 })

package/src/ProgramJudge.ts

@@ -0,0 +1,186 @@
+import * as Effect from "effect/Effect"
+import { Sample, type Dimension, type EvalResult } from "@llm4ts/core/eval/Eval"
+import type { Evaluator } from "@llm4ts/core/eval/Evaluator"
+import { capped, withShrink } from "./Context.ts"
+import { FlowLlmError, type FlowError } from "./FlowError.ts"
+import { FlowEvents, Info } from "./FlowEvents.ts"
+import type { GitToolShape } from "./GitTool.ts"
+import type { Pack } from "./Pack.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+import { ReviewIssue, ReviewResult, mergeReviewResults } from "./Review.ts"
+import { cachedReview } from "./ReviewCache.ts"
+
+// Per-program spec-compliance judging, shared by the implement and review
+// phases. A whole-branch judge call carries every spec and every diff hunk in
+// the estate, which is what blows a provider's input window. Judging one
+// program at a time against only that program's slice of the diff keeps each
+// call small, and — wrapped in the review cache — makes the gate resumable: an
+// unchanged program reuses its stored verdict with no LLM call.
+
+export interface GroupedFiles {
+  readonly byProgram: Readonly<Record<string, ReadonlyArray<string>>>
+  readonly unassigned: ReadonlyArray<string>
+}
+
+/**
+ * Partition `changed` by which program's file regex matches. A file matching
+ * several programs is judged with each of them (a shared bridge class is
+ * genuinely part of both). The remainder — build files, shared utilities — is
+ * returned separately for the unassigned pass.
+ */
+export const groupFiles = (
+  pack: Pack,
+  programs: ReadonlyArray<string>,
+  changed: ReadonlyArray<string>
+): GroupedFiles => {
+  const byProgram = Object.fromEntries(
+    programs.map((program) => {
+      const matches = pack.filesFor(program)
+      return [program, changed.filter((file) => matches.test(file))] as const
+    })
+  )
+  const assigned = new Set(Object.values(byProgram).flat())
+  return {
+    byProgram,
+    unassigned: changed.filter((file) => !assigned.has(file))
+  }
+}
+
+export interface ProgramJudgeOptions {
+  readonly pack: Pack
+  readonly judge: Evaluator<Sample>
+  readonly dimensions: ReadonlyArray<Dimension>
+  readonly git: GitToolShape
+  readonly files: PlainFileStoreShape
+  /** Directory holding the per-program verdict cache (`<gateDir>/<NAME>.json`). */
+  readonly gateDir: string
+  readonly base: string
+  readonly programs: ReadonlyArray<string>
+  /** A program's spec text; the caller owns where specs live. */
+  readonly specFor: (program: string) => Effect.Effect<string, FlowError>
+  readonly query: string
+  /** Content fingerprint for the verdict cache (hashing lives outside flow). */
+  readonly fingerprint: (...parts: ReadonlyArray<string>) => string
+}
+
+const join = (root: string, path: string): string =>
+  `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
+
+const rubricText = (dimensions: ReadonlyArray<Dimension>): string =>
+  dimensions
+    .map((dimension) => `${dimension.name} (0..${dimension.maxScore}): ${dimension.rubric}`)
+    .join("\n")
+
+/**
+ * Sub-bar dimensions as Critical review issues, titled with the program they
+ * belong to — the same shape the extract gate produces, so fix loops and
+ * `ReviewResult.isClean` work unchanged.
+ */
+const issues = (
+  scored: EvalResult,
+  dimensions: ReadonlyArray<Dimension>,
+  program: string
+): ReviewResult => {
+  const subBar = scored.scores.filter(
+    (score) =>
+      score.score < (dimensions.find((dimension) => dimension.name === score.name)?.maxScore ?? 2)
+  )
+  return ReviewResult.make({
+    issues: subBar.map((score) =>
+      ReviewIssue.make({
+        severity: "Critical",
+        title: `judge[${program}]: ${score.name} scored ${score.score}`,
+        description: score.reasoning
+      })
+    ),
+    summary: `judge:${program}`
+  })
+}
+
+/**
+ * A spec'd program with NO matching changed file is a deterministic gate
+ * failure, not a silent pass. Skipping it would let the branch clear a bar the
+ * old whole-branch judge would have failed. It also surfaces a mis-set
+ * `programFiles:` immediately — the top documented risk of the per-program
+ * design — instead of quietly degrading coverage.
+ */
+export const unimplemented = (programs: ReadonlyArray<string>): ReviewResult =>
+  ReviewResult.make({
+    issues: programs.map((program) =>
+      ReviewIssue.make({
+        severity: "Critical",
+        title: `judge[${program}]: spec'd but no implementation files changed`,
+        description:
+          `${program} has a committed spec but no file on this branch matches the pack's ` +
+          "programFiles regex for it. Either the program is unimplemented, or the pack's " +
+          "`programFiles:` template does not match this repo's layout — check that before " +
+          "assuming the former."
+      })
+    ),
+    summary: "judge:unimplemented"
+  })
+
+const judgeSlice = Effect.fn("@llm4ts/flow/ProgramJudge.judgeSlice")(function* (
+  options: ProgramJudgeOptions,
+  label: string,
+  spec: string,
+  diff: string
+): Effect.fn.Return<ReviewResult, FlowError, FlowEvents> {
+  const events = yield* FlowEvents
+  const rubric = rubricText(options.dimensions)
+  return yield* cachedReview(
+    options.files,
+    join(options.gateDir, `${label}.json`),
+    options.fingerprint(spec, diff, rubric),
+    events.publish(Info.make({ message: `judging ${label}` })).pipe(
+      Effect.andThen(
+        withShrink(`judge[${label}]`, (cap) =>
+          Effect.gen(function* () {
+            const cappedSpec = yield* capped(`spec[${label}]`, spec, cap)
+            const cappedDiff = yield* capped(`diff[${label}]`, diff, cap)
+            return yield* options.judge
+              .evaluate(
+                Sample.make({ response: cappedDiff, context: cappedSpec, query: options.query })
+              )
+              .pipe(Effect.mapError(FlowLlmError.from))
+          })
+        )
+      ),
+      Effect.map((scored) => issues(scored, options.dimensions, label))
+    )
+  )
+})
+
+/**
+ * Judge every program whose files changed, plus one pass over the unassigned
+ * remainder. Each verdict is cached at `gateDir/<NAME>.json`, fingerprinted
+ * over the spec, the diff slice, and the rubric it judged — so re-running
+ * after a crash re-judges only what changed.
+ */
+export const judgeAllPrograms = Effect.fn("@llm4ts/flow/ProgramJudge.judgeAll")(function* (
+  options: ProgramJudgeOptions
+): Effect.fn.Return<ReviewResult, FlowError, FlowEvents> {
+  const changed = yield* options.git.changedFilesVsBase(options.base)
+  const { byProgram, unassigned } = groupFiles(options.pack, options.programs, changed)
+  const active = options.programs.filter((program) => (byProgram[program] ?? []).length > 0)
+  const untouched = options.programs.filter((program) => (byProgram[program] ?? []).length === 0)
+
+  const perProgram: Array<ReviewResult> = []
+  for (const program of active) {
+    const spec = yield* options.specFor(program)
+    // The file slice comes from groupFiles — re-deriving it per program would
+    // be N+1 git invocations for the same answer.
+    const diff = yield* options.git.diffVsBaseScoped(options.base, byProgram[program] ?? [])
+    perProgram.push(yield* judgeSlice(options, program, spec, diff))
+  }
+
+  if (unassigned.length > 0) {
+    const diff = yield* options.git.diffVsBaseScoped(options.base, unassigned)
+    const specs = yield* Effect.forEach(options.programs, options.specFor).pipe(
+      Effect.map((all) => all.join("\n\n"))
+    )
+    perProgram.push(yield* judgeSlice(options, "unassigned", specs, diff))
+  }
+
+  return mergeReviewResults([...perProgram, unimplemented(untouched)])
+})

package/src/Provenance.ts

@@ -13,7 +13,16 @@ export class Provenance extends Schema.Class<Provenance>("Provenance")({
   specs: Schema.Record(Schema.String, Schema.String),
   gateVerdicts: Schema.Record(Schema.String, Schema.String),
   equivalenceReport: Schema.optionalKey(Schema.String),
-  fixSpecs: Schema.Array(Schema.String)
+  fixSpecs: Schema.Array(Schema.String),
+  // Context truncations recorded while producing this evidence
+  // (Context.renderTruncation strings). A gate verdict rendered on a
+  // partially-read spec pack says so HERE — that visibility is the whole
+  // reason truncation is allowed at all. Defaulted so manifests written
+  // before this field still load.
+  contextTruncations: Schema.Array(Schema.String).pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed([])),
+    Schema.withConstructorDefault(Effect.succeed([]))
+  )
 }) {}
 
 const join = (root: string, path: string): string =>

package/src/Survey.ts

@@ -29,6 +29,43 @@ export class SurveyGraph extends Schema.Class<SurveyGraph>("SurveyGraph")({
   }
 }
 
+/**
+ * The transitive dependency closure of `program` as repo-relative paths,
+ * breadth-first, excluding the program itself. The `seen` set is required, not
+ * optional bookkeeping: COBOL copybook graphs genuinely contain cycles (a
+ * copybook that COPYs something which eventually COPYs back), and without it
+ * this walk would never terminate on a real estate. Truncated to `maxFiles` so
+ * a program pulling hundreds of copybooks still gets a bounded, visible subset
+ * instead of an unbounded read.
+ */
+export const closureFor = (
+  graph: SurveyGraph,
+  program: string,
+  maxFiles: number
+): ReadonlyArray<string> => {
+  const pathOf = new Map(graph.nodes.map((node) => [node.name, node.path]))
+  const walk = (
+    frontier: ReadonlyArray<string>,
+    seen: ReadonlySet<string>,
+    acc: ReadonlyArray<string>
+  ): ReadonlyArray<string> => {
+    if (frontier.length === 0 || acc.length >= maxFiles) {
+      return acc.slice(0, maxFiles)
+    }
+    const next = [
+      ...new Set(frontier.flatMap((from) => graph.outgoing(from).map((edge) => edge.to)))
+    ].filter((name) => !seen.has(name))
+    return walk(next, new Set([...seen, ...next]), [
+      ...acc,
+      ...next.flatMap((name) => {
+        const path = pathOf.get(name)
+        return path === undefined ? [] : [path]
+      })
+    ])
+  }
+  return walk([program], new Set([program]), [])
+}
+
 const unitName = (path: string): string => {
   const base = path.split("/").at(-1) ?? path
   const dot = base.lastIndexOf(".")

package/src/TransientRetry.ts

@@ -27,12 +27,40 @@ const transientSignals: ReadonlyArray<string> = [
   " 504"
 ]
 
+// An "empty response" is ambiguous: gemini returns one both for a random mid-stream
+// flake and for a prompt too large to start on. This classifier sees only the message,
+// so it deliberately treats both as flaky — a fresh process fixes the common (flake)
+// case, and the oversized-prompt case is resolved a layer up by Context.withShrink.
+// Do not route empty responses into isContextOverflow.
 const flakyStreamSignals: ReadonlyArray<string> = [
   "empty response",
   "malformed tool call",
   "invalid stream"
 ]
 
+// Deterministic client errors a retry can never fix. Gemini wraps every error in
+// "[API Error: {...}]", including 400s, so the "api error" transient signal would
+// otherwise swallow them.
+const deterministic4xxSignals: ReadonlyArray<string> = [
+  "invalid_argument",
+  '"code": 400',
+  '"code":400',
+  "code=400",
+  "exceeds the maximum number of tokens"
+]
+
+// The message signatures of a prompt-too-large failure, in one place: isContextOverflow
+// matches them on a typed LlmError, and Context.withShrink matches them on a bare
+// message string when no typed cause survived. Two copies of this list would drift.
+const contextOverflowSignals: ReadonlyArray<string> = [
+  "exceeds the maximum number of tokens",
+  "input token count exceeds",
+  "context length exceeded",
+  "maximum context length",
+  "prompt is too long",
+  "request too large"
+]
+
 const includesSignal = (message: string, signals: ReadonlyArray<string>): boolean => {
   const normalized = message.toLowerCase()
   return signals.some((signal) => normalized.includes(signal))
@@ -41,13 +69,29 @@ const includesSignal = (message: string, signals: ReadonlyArray<string>): boolea
 export const isFlakyStream = (error: LlmError): boolean =>
   error._tag === "ProviderError" && includesSignal(error.message, flakyStreamSignals)
 
+const isDeterministic4xx = (message: string): boolean =>
+  includesSignal(message, deterministic4xxSignals)
+
+export const isContextOverflowMessage = (message: string): boolean =>
+  includesSignal(message, contextOverflowSignals)
+
+// The prompt was larger than the model's input window. Deterministic: the same prompt
+// always fails, so it is not transient — it routes to Context.withShrink, which retries
+// at a smaller budget.
+export const isContextOverflow = (error: LlmError): boolean =>
+  error._tag === "ProviderError" && isContextOverflowMessage(error.message)
+
 export const isTransient = (error: LlmError): boolean => {
   switch (error._tag) {
     case "TimeoutError":
     case "RateLimitError":
       return true
     case "ProviderError":
-      return !isFlakyStream(error) && includesSignal(error.message, transientSignals)
+      return (
+        !isFlakyStream(error) &&
+        !isDeterministic4xx(error.message) &&
+        includesSignal(error.message, transientSignals)
+      )
     default:
       return false
   }