@llm4ts/runner 3.3.0 → 3.4.0

package/src/EventPresentation.ts

@@ -0,0 +1,168 @@
+import * as Schema from "effect/Schema"
+import type { FlowEvent, FlowEventByTag, FlowEventTag } from "@llm4ts/flow/FlowEvents"
+
+export const Verbosity = Schema.Literals(["Quiet", "Normal", "Verbose", "Debug"])
+export type Verbosity = typeof Verbosity.Type
+
+const rank: Readonly<Record<Verbosity, number>> = { Quiet: 0, Normal: 1, Verbose: 2, Debug: 3 }
+
+/** Whether `verbosity` is `least` or louder. */
+export const atLeast = (verbosity: Verbosity, least: Verbosity): boolean =>
+  rank[verbosity] >= rank[least]
+
+/** A line of `llm4ts watch` and of the MCP run digests, and the lane it is filed under. */
+export interface DigestLine {
+  readonly text: string
+  readonly lane?: string
+}
+
+/** How one event shows: on the terminal, in a profile's gaps, in a digest. */
+export interface Presentation<E> {
+  /**
+   * Whether the terminal prints it as a line of its own: `never`, from a
+   * verbosity up (`Quiet`: always), or by a rule of its own.
+   */
+  readonly line: "never" | Verbosity | ((event: E, verbosity: Verbosity) => boolean)
+  /** The event by kind, never its content: how `llm4ts profile` names it around a gap. */
+  readonly kind: string | ((event: E) => string)
+  /** Its line in a digest. Absent: digests leave the event out. */
+  readonly digest?: (event: E) => DigestLine
+}
+
+const laned = (lane: string | undefined): { readonly lane?: string } =>
+  lane === undefined ? {} : { lane }
+
+const capability = "a capability check"
+const roster = "a roster change"
+const other = "an event"
+
+/**
+ * Screen and digest policy for every event. Exhaustive by type: adding an
+ * event class without an entry here fails `pnpm typecheck`.
+ */
+export const eventPresentation: {
+  readonly [K in FlowEventTag]: Presentation<FlowEventByTag[K]>
+} = {
+  // Advise mode publishes a separate Info event for the operator.
+  JudgmentObserved: { line: "never", kind: other },
+  // For the trace file.
+  BlackboardRun: { line: "never", kind: other },
+  StageStarted: { line: "Quiet", kind: "a stage start" },
+  StageCompleted: { line: "Quiet", kind: "a stage end" },
+  StageFailed: {
+    line: "Quiet",
+    kind: "a stage failure",
+    digest: (event) => ({ text: `${event.stage} failed: ${event.message}`, ...laned(event.lane) })
+  },
+  Aborted: {
+    line: "Quiet",
+    kind: other,
+    digest: (event) => ({ text: `aborted: ${event.message}` })
+  },
+  Info: { line: "Normal", kind: "a log note" },
+  ToolUse: { line: "Normal", kind: "a coder tool call" },
+  AssistantMessage: { line: "Normal", kind: "an assistant message" },
+  TokensUsed: { line: "Verbose", kind: "a token report" },
+  // Progress feeds the status rows.
+  UsageProgress: { line: "never", kind: other },
+  ReviewFindings: { line: "Normal", kind: "a review round" },
+  // Every git read and gate command is a capability event: useful in a
+  // trace, noise on screen once several stories run.
+  CapabilityUsed: { line: "Verbose", kind: capability },
+  CapabilityDenied: { line: "Quiet", kind: capability },
+  CapabilityUnenforceable: {
+    line: "Quiet",
+    kind: capability,
+    digest: (event) => ({ text: `capability unenforceable: ${event.detail}` })
+  },
+  EvidenceChecked: { line: "Quiet", kind: "an evidence check" },
+  ReviewFindingDemoted: { line: "Quiet", kind: "a review finding demoted" },
+  Declassified: { line: "Normal", kind: other },
+  ExecutorLeased: { line: "Normal", kind: roster },
+  // A lease ending is routine.
+  ExecutorReleased: { line: "never", kind: roster },
+  ExecutorExcluded: {
+    line: "Normal",
+    kind: roster,
+    digest: (event) => ({ text: `${event.executor} excluded: ${event.reason}` })
+  },
+  ExecutorResumed: { line: "Normal", kind: roster },
+  ExecutorHandedOver: {
+    line: "Normal",
+    kind: roster,
+    digest: (event) => ({
+      text: `${event.from} handed over ${event.role} (${event.scope}): ${event.reason}`,
+      ...laned(event.label)
+    })
+  },
+  // The story's outcome already says whether the judge cleared it.
+  StoryJudged: {
+    line: "never",
+    kind: "a judge verdict",
+    digest: (event) => ({
+      text: `${event.lane} judged round ${event.round}: ${event.cleared ? "cleared" : `${event.issues} issues`}`,
+      lane: event.lane
+    })
+  },
+  RoundtableTurn: { line: "never", kind: "a roundtable turn" },
+  BriefReported: { line: "never", kind: "a brief report" },
+  Timed: {
+    line: "never",
+    kind: (event) => {
+      switch (event.kind) {
+        case "model":
+          return `the end of a ${event.label} call`
+        case "tool":
+          return `the end of tool ${event.label}`
+        case "gate":
+          return `the end of gate ${event.label}`
+        case "wait":
+          return `the end of a wait for the ${event.label}`
+        default:
+          return `the end of ${event.label}`
+      }
+    }
+  },
+  Began: {
+    // A gate or a setup may run for many minutes: its start is a line, so a
+    // long one reads as running, not stuck. Other work starts too often.
+    line: (event, verbosity) => event.kind === "gate" && verbosity !== "Quiet",
+    kind: (event) =>
+      event.kind === "model"
+        ? `the start of a ${event.label} call`
+        : `the start of ${event.kind} ${event.label}`,
+    digest: (event) => ({ text: `began ${event.kind} ${event.label}`, ...laned(event.lane) })
+  },
+  TasksPlanned: { line: "never", kind: other },
+  TaskStarted: { line: "never", kind: other },
+  TaskCompleted: { line: "never", kind: other },
+  StoryStatusChanged: {
+    line: "never",
+    kind: other,
+    digest: (event) => ({ text: `story ${event.id} ${event.status}`, lane: event.id })
+  },
+  CriterionChecked: {
+    line: "Normal",
+    kind: other,
+    digest: (event) => ({ text: `criterion ${event.tag} ${event.status}`, lane: event.story })
+  },
+  Parked: {
+    line: "Normal",
+    kind: other,
+    digest: (event) => ({ text: `parked ${event.item}: ${event.reason}`, lane: event.story })
+  }
+}
+
+// A tag and its event are one value's, so the entry found by the tag takes
+// the event. TypeScript does not correlate the two across the union; reading
+// the entry through a generic key is the step that lets it.
+const entryOf = <K extends FlowEventTag>(tag: K): Presentation<FlowEventByTag[K]> =>
+  eventPresentation[tag]
+
+/** The entry of an event, to apply to that event. */
+export const presentationOf = (event: FlowEvent): Presentation<FlowEvent> => entryOf(event._tag)
+
+/** The tags a digest shows: the entries with a `digest`. */
+export const digestedTags: ReadonlyArray<string> = Object.entries(eventPresentation)
+  .filter(([, entry]) => entry.digest !== undefined)
+  .map(([tag]) => tag)

package/src/ExecutorRoster.ts

@@ -33,6 +33,7 @@ import {
   effortOf,
   type Role
 } from "@llm4ts/flow/Roster"
+import { settingValue } from "@llm4ts/flow/Settings"
 import { apiPresetFor, asReadOnly, coderFor, withEnvironment, withModel } from "./Connectors.ts"
 
 type Environment = Readonly<Record<string, string | undefined>>
@@ -188,11 +189,11 @@ export interface RosterSource {
 export const loadRosterDocument = Effect.fn("@llm4ts/runner/ExecutorRoster.load")(function* (
   source: RosterSource
 ): Effect.fn.Return<RosterDocument | undefined, FlowError> {
-  const chosen = source.environment.LLM4TS_ROSTER?.trim()
+  const chosen = settingValue("LLM4TS_ROSTER", source.environment)
   if (chosen === "none") {
     return undefined
   }
-  const loaded = yield* chosen !== undefined && chosen.length > 0
+  const loaded = yield* chosen !== undefined
     ? Effect.flatMap(readRoster(source.files, chosen), (document) =>
         document === undefined
           ? Effect.fail(RosterInvalid.make({ path: chosen, violations: ["no roster file there"] }))
@@ -218,10 +219,7 @@ export const loadRosterDocument = Effect.fn("@llm4ts/runner/ExecutorRoster.load"
     return undefined
   }
   const { document, where } = loaded
-  const ids = (source.environment.LLM4TS_EXECUTORS ?? "")
-    .split(",")
-    .map((id) => id.trim())
-    .filter((id) => id.length > 0)
+  const ids = settingValue("LLM4TS_EXECUTORS", source.environment) ?? []
   const unknown = ids.filter((id) => !document.executors.some((spec) => spec.id === id))
   const narrowed = narrowRoster(document, ids)
   const violations = [

package/src/FlowArgs.ts

@@ -2,6 +2,7 @@ import { readFile, stat } from "node:fs/promises"
 import { resolve } from "node:path"
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
+import { connectorTable, offeredCoderNames } from "@llm4ts/core/Models"
 
 export interface FlowArgs {
   readonly promptText?: string
@@ -11,6 +12,10 @@ export interface FlowArgs {
   readonly version?: boolean
 }
 
+const firstCredentialVariables = Object.values(connectorTable).flatMap((row) =>
+  row.kind === "Api" ? row.credentialVariables.slice(0, 1) : []
+)
+
 export const FlowUsage =
   'usage: llm4ts ["<prompt>" | --prompt-file <path> | @<path>] [--repo <path>] | llm4ts doctor'
 
@@ -30,13 +35,13 @@ commands:
   doctor                  check connector availability and credentials
 
 environment:
-  LLM4TS_CODER            coding agent: claude|codex|gemini|pi|agy|grok|cursor|opencode (default: claude)
+  LLM4TS_CODER            coding agent: ${offeredCoderNames.join("|")} (default: claude)
   LLM4TS_VERBOSITY        terminal verbosity: quiet|normal|verbose
   LLM4TS_UI               tree: the full-screen agent tree (ADR 0022; q returns to the classic view)
   LLM4TS_TRANSCRIPT       on: record each seat's input and output under .llm4ts/transcripts/
   LLM4TS_OTEL             on: export spans over OTLP (a local Phoenix at localhost:6006 unless OTEL_* says otherwise)
   LLM4TS_OTEL_CONTENT     on|full: prompts, replies and tool I/O travel too (off by default)
-  OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY
+  ${firstCredentialVariables.join(", ")}
                           credentials for API providers
 
 A trace of each run is written under .llm4ts/ in the target repository.

package/src/FlowRunner.ts

@@ -27,6 +27,7 @@ import { createConnectorRegistry } from "@llm4ts/core/providers/ConnectorFactori
 import { ConnectorIds } from "@llm4ts/core/Models"
 import { ProviderError } from "@llm4ts/core/Errors"
 import { makeCostTracker, type CostTracker } from "@llm4ts/flow/CostTracker"
+import { settingValue } from "@llm4ts/flow/Settings"
 import { runGeminiAcpBridge } from "./NodeGeminiAcpBridge.ts"
 import { runGeminiModelBridge } from "./NodeGeminiModelBridge.ts"
 import {
@@ -51,7 +52,7 @@ import {
   type FlowError
 } from "@llm4ts/flow/FlowError"
 import {
-  defaultDrainTimeout,
+  type DrainReport,
   FlowEvents,
   FlowEventsValues,
   Info,
@@ -264,12 +265,6 @@ export interface FlowRunnerBundle {
   readonly announceStartupNotices: Effect.Effect<void>
 }
 
-const truthy = (value: string | undefined): boolean =>
-  value !== undefined && ["1", "true", "on", "yes"].includes(value.trim().toLowerCase())
-
-const switchedOff = (value: string | undefined): boolean =>
-  value !== undefined && ["0", "false", "no", "off"].includes(value.trim().toLowerCase())
-
 const isPiSeat = (config: ConnectorConfig | undefined): config is CliConnectorConfig =>
   config instanceof CliConnectorConfig && config.connectorId.value === ConnectorIds.Pi.value
 
@@ -289,7 +284,7 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
   environment: Readonly<Record<string, string | undefined>>
 ): Effect.fn.Return<(config: ConnectorConfig) => ConnectorConfig, FlowError, Scope.Scope> {
   const identity = (config: ConnectorConfig): ConnectorConfig => config
-  if (!truthy(environment.LLM4TS_GEMINI_BRIDGE)) {
+  if (!settingValue("LLM4TS_GEMINI_BRIDGE", environment)) {
     return identity
   }
   // The reasoning seat defaults to the coder, so a pi coder makes this a pi
@@ -304,7 +299,7 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
   const resolution = resolveBridgeModel(
     readPiModelsJson(),
     port,
-    environment.LLM4TS_GEMINI_BRIDGE_MODEL
+    settingValue("LLM4TS_GEMINI_BRIDGE_MODEL", environment)
   )
   const problem = bridgeModelProblem(resolution, port)
   if (problem !== undefined || resolution._tag !== "Resolved") {
@@ -322,8 +317,9 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
       })
     )
   }
-  const geminiModel =
-    environment.LLM4TS_GEMINI_MODEL === undefined ? {} : { model: environment.LLM4TS_GEMINI_MODEL }
+  const requestModel = settingValue("LLM4TS_GEMINI_MODEL", environment)
+  const geminiModel = requestModel === undefined ? {} : { model: requestModel }
+  const token = settingValue("LLM4TS_GEMINI_BRIDGE_TOKEN", environment)
   if (mode.mode === "model") {
     // ADR 0037: one locked-down `gemini` call per request, in an empty
     // directory so no project GEMINI.md reaches the model.
@@ -337,10 +333,7 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
       executor: dependencies.process,
       temporaryFiles: dependencies.temporaryFiles ?? nodeTemporaryFiles,
       ...geminiModel,
-      ...(environment.LLM4TS_GEMINI_BRIDGE_TOKEN === undefined ||
-      environment.LLM4TS_GEMINI_BRIDGE_TOKEN.length === 0
-        ? {}
-        : { token: environment.LLM4TS_GEMINI_BRIDGE_TOKEN })
+      ...(token === undefined ? {} : { token })
     }).pipe(Effect.mapError(FlowLlmError.from))
   } else {
     yield* runGeminiAcpBridge({
@@ -368,8 +361,8 @@ export const runIdentityFromEnvironment = (
   options: Pick<FlowRunnerOptions, "runId" | "tracePath">,
   environment: Readonly<Record<string, string | undefined>>
 ): { readonly runId?: string; readonly tracePath?: string } => {
-  const runId = nonBlank(options.runId) ?? nonBlank(environment["LLM4TS_RUN_ID"])
-  const tracePath = nonBlank(options.tracePath) ?? nonBlank(environment["LLM4TS_TRACE_PATH"])
+  const runId = nonBlank(options.runId) ?? settingValue("LLM4TS_RUN_ID", environment)
+  const tracePath = nonBlank(options.tracePath) ?? settingValue("LLM4TS_TRACE_PATH", environment)
   return {
     ...(runId === undefined ? {} : { runId }),
     ...(tracePath === undefined ? {} : { tracePath })
@@ -521,7 +514,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   // notably the judgment seat and the worktree seats `contextFor` rebinds.
   const runEnvironment = options.environment ?? process.env
   const estimateOptions = estimatedUsageOptionsFromEnv(runEnvironment)
-  const meterUsage = options.estimateUsage ?? !switchedOff(runEnvironment.LLM4TS_ESTIMATE_USAGE)
+  const meterUsage = options.estimateUsage ?? settingValue("LLM4TS_ESTIMATE_USAGE", runEnvironment)
   // Every seat's spans (ADR 0026): content only when asked, an estimate on a
   // call the backend reports no usage for, and who served it when known.
   const seatOptions = (executor?: Effect.Effect<string | undefined>): TimedSeatOptions => ({
@@ -578,11 +571,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
     seatConfig: ConnectorConfig,
     environment: Readonly<Record<string, string | undefined>>
   ): Effect.Effect<JudgmentShape, FlowError> => {
-    const backend =
-      options.judgmentBackend ??
-      (environment.LLM4TS_JUDGMENT_BACKEND?.trim().toLowerCase() === "typesafe"
-        ? "typesafe"
-        : "llm")
+    const backend = options.judgmentBackend ?? settingValue("LLM4TS_JUDGMENT_BACKEND", environment)
     if (backend !== "typesafe") {
       return Effect.succeed(
         makeLlmJudgment(
@@ -592,7 +581,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
             ...(seatConfig.model === undefined ? {} : { model: seatConfig.model }),
             // LLM4TS_JUDGMENT_BATCHING=shared-prefix sends each request's state
             // once with every question; anything else keeps them independent.
-            ...(environment.LLM4TS_JUDGMENT_BATCHING?.trim().toLowerCase() === "shared-prefix"
+            ...(settingValue("LLM4TS_JUDGMENT_BATCHING", environment) === "shared-prefix"
               ? { batching: "shared-prefix" as const }
               : {})
           }),
@@ -987,6 +976,21 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   }
 })
 
+/** What the run prints when `drained` reports a consumer short. */
+export const drainShortfall = (report: DrainReport): string => {
+  const behind = report.behind.map(
+    (consumer) => `${consumer.name} was ${consumer.missing.toString()} event(s) behind`
+  )
+  const late = report.late.map(
+    (consumer) =>
+      `${consumer.name} started listening after ${consumer.missed.toString()} event(s) were published`
+  )
+  return (
+    `some run events were still unconsumed: ${[...late, ...behind].join("; ")}. ` +
+    "The totals below, the ledger, and the trace may be short"
+  )
+}
+
 /** `claude (coder·reviewer·judge ×3)` — how the run header names an executor. */
 const describeExecutor = (spec: ExecutorSpec): string =>
   `${spec.id} (${rolesOf(spec).join("·")} ×${spec.slots ?? 1})`
@@ -1004,7 +1008,8 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   const dependencies = withRunStateIgnore(given)
   const startedAt = yield* Clock.currentTimeMillis
   const environment = options.environment ?? process.env
-  const verbosity = options.verbosity ?? parseVerbosity(environment.LLM4TS_VERBOSITY)
+  const verbosity =
+    options.verbosity ?? parseVerbosity(settingValue("LLM4TS_VERBOSITY", environment))
   const persistRun = options.persistRun ?? true
   // OpenTelemetry export (ADR 0026): decided from the environment, built once
   // per run, flushed when the run's scope closes.
@@ -1043,7 +1048,7 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   const surface = tree?.surface ?? classic
   const palette = surface.palette
   const terminal = yield* consumeTerminalEvents(bundle.events, surface, verbosity, {
-    timestamps: environment.LLM4TS_TIMESTAMPS === "1" || environment.LLM4TS_TIMESTAMPS === "true"
+    timestamps: settingValue("LLM4TS_TIMESTAMPS", environment)
   })
   if (verbosity !== "Quiet") {
     const reviewers = options.reviewers ?? []
@@ -1130,10 +1135,11 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
     tracePath === undefined
       ? bundle.context
       : { ...bundle.context, trace: { runId: bundle.runId, path: tracePath } }
+  const flow = settingValue("LLM4TS_FLOW", environment)
   const runAttributes: Record<string, unknown> = {
     [attr.run]: bundle.runId,
     [attr.session]: bundle.runId,
-    ...(environment.LLM4TS_FLOW === undefined ? {} : { [attr.flow]: environment.LLM4TS_FLOW })
+    ...(flow === undefined ? {} : { [attr.flow]: flow })
   }
   // The run is a CHAIN span every other span descends from or links to; its
   // attributes ride on all of them. Effect's own function spans stay
@@ -1159,33 +1165,13 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
     Effect.provideService(FlowContext, context),
     Effect.andThen((value) => Effect.as(enforceBudget, value)),
     Effect.ensuring(
-      Effect.all(
-        [
-          terminal.awaitDrained(),
-          Effect.all(
-            [
-              tracker.awaitDrained(bundle.events),
-              recorder === undefined ? Effect.succeed(true) : recorder.awaitDrained(bundle.events),
-              bundle.judgmentLog === undefined
-                ? Effect.succeed(true)
-                : bundle.judgmentLog.awaitDrained(bundle.events)
-            ],
-            { concurrency: "unbounded" }
-          )
-        ],
-        { concurrency: "unbounded" }
-      ).pipe(
-        // A consumer that gave up before catching up leaves the totals below
-        // short. Say so rather than printing a quietly incomplete summary.
-        Effect.flatMap(([, accounted]) =>
-          accounted.every((drained) => drained)
-            ? Effect.void
-            : surface.log(
-                palette.fail(
-                  `some run events were still unconsumed after ${defaultDrainTimeout} — ` +
-                    "the totals below, the ledger, and the trace may be short"
-                )
-              )
+      // One wait for every consumer of the run: the terminal, the totals,
+      // the trace, the judgment log. A consumer that fell short leaves the
+      // totals below short, so the run names it instead of printing a
+      // quietly incomplete summary.
+      bundle.events.drained().pipe(
+        Effect.flatMap((report) =>
+          report.complete ? Effect.void : surface.log(palette.fail(drainShortfall(report)))
         ),
         Effect.andThen(tree === undefined ? Effect.void : tree.close),
         Effect.andThen(appendLedger),
@@ -1254,7 +1240,7 @@ const wantsAgentTree = (
   output: { readonly isTTY?: boolean; readonly columns?: number },
   input: { readonly isTTY?: boolean }
 ): boolean =>
-  environment.LLM4TS_UI === "tree" &&
+  settingValue("LLM4TS_UI", environment) === "tree" &&
   environment.NO_COLOR === undefined &&
   output.isTTY === true &&
   input.isTTY === true &&

package/src/NodeGeminiCliExecutor.ts

@@ -19,6 +19,9 @@ import {
 } from "@llm4ts/core/providers/GeminiCliProvider"
 import { nodeProcessExecutor } from "./NodeProcessExecutor.ts"
 import { nodeTemporaryFiles } from "./NodeTemporaryFiles.ts"
+import { cliExecutable } from "@llm4ts/core/Models"
+
+const executable = cliExecutable("GeminiCli")
 
 const failure = (message: string): ProviderError => ProviderError.make({ message })
 
@@ -47,7 +50,7 @@ export const makeNodeGeminiCliExecutor = (
   const supportsAdminPolicy: Effect.Effect<boolean> = Effect.suspend(() =>
     adminPolicy !== undefined
       ? Effect.succeed(adminPolicy)
-      : executor.run(["gemini", "--help"], process.cwd(), {}).pipe(
+      : executor.run([executable, "--help"], process.cwd(), {}).pipe(
           Effect.map((result) =>
             geminiSupportsAdminPolicy([...result.stdout, ...result.stderr].join("\n"))
           ),
@@ -75,7 +78,7 @@ export const makeNodeGeminiCliExecutor = (
     )
   return {
     checkGeminiInstalled: executor
-      .run(["gemini", "--version"], process.cwd(), {})
+      .run([executable, "--version"], process.cwd(), {})
       .pipe(
         Effect.flatMap((result) =>
           result.exitCode === 0
@@ -89,7 +92,7 @@ export const makeNodeGeminiCliExecutor = (
           const environment = yield* environmentFor(context)
           const args = yield* argsFor(config, context, "json")
           const result = yield* executor.runWithStdin(
-            ["gemini", ...args],
+            [executable, ...args],
             context.cwd ?? process.cwd(),
             environment,
             prompt
@@ -111,7 +114,7 @@ export const makeNodeGeminiCliExecutor = (
             ([environment, args]) =>
               executor
                 .runStreamingWithStdin(
-                  ["gemini", ...args],
+                  [executable, ...args],
                   context.cwd ?? process.cwd(),
                   environment,
                   prompt

package/src/NodeGeminiModelBridge.ts

@@ -34,6 +34,9 @@ import {
   requestPath,
   writeJson
 } from "./NodeGeminiAcpBridge.ts"
+import { cliExecutable } from "@llm4ts/core/Models"
+
+const executable = cliExecutable("GeminiCli")
 
 /**
  * The bridge's model route (ADR 0037): `/v1/chat/completions` in OpenAI's
@@ -131,7 +134,7 @@ const geminiTurn = (
         config.executor
           .runStreamingWithStdin(
             [
-              "gemini",
+              executable,
               // Bound to its flag, so it can never read as a flag of its own.
               `--model=${model}`,
               "--output-format",

package/src/Otel.ts

@@ -12,6 +12,7 @@ import * as OtlpExporter from "effect/observability/OtlpExporter"
 import * as OtlpMetrics from "effect/observability/OtlpMetrics"
 import * as OtlpSerialization from "effect/observability/OtlpSerialization"
 import * as OtlpTracer from "effect/observability/OtlpTracer"
+import { settingValue } from "@llm4ts/flow/Settings"
 import { packageVersion } from "./Package.ts"
 
 export type OtelConfig =
@@ -23,8 +24,6 @@ export const phoenixTracesUrl = "http://localhost:6006/v1/traces"
 
 const truthy = (value: string | undefined): boolean =>
   /^(on|1|true|yes)$/iu.test(value?.trim() ?? "")
-const falsy = (value: string | undefined): boolean =>
-  /^(off|0|false|no)$/iu.test(value?.trim() ?? "")
 
 /**
  * Off unless asked. An OTLP endpoint in the environment wins and is used as
@@ -34,7 +33,8 @@ const falsy = (value: string | undefined): boolean =>
 export const otelConfig = (
   environment: Readonly<Record<string, string | undefined>>
 ): OtelConfig => {
-  if (truthy(environment.OTEL_SDK_DISABLED) || falsy(environment.LLM4TS_OTEL)) {
+  const asked = settingValue("LLM4TS_OTEL", environment)
+  if (truthy(environment.OTEL_SDK_DISABLED) || asked === false) {
     return { mode: "off" }
   }
   // Under the test runner the exporter's sleeps run on a TestClock nobody
@@ -49,9 +49,7 @@ export const otelConfig = (
   if (endpoint !== undefined && endpoint.length > 0) {
     return { mode: "env", endpoint }
   }
-  return truthy(environment.LLM4TS_OTEL)
-    ? { mode: "phoenix", tracesUrl: phoenixTracesUrl }
-    : { mode: "off" }
+  return asked === true ? { mode: "phoenix", tracesUrl: phoenixTracesUrl } : { mode: "off" }
 }
 
 export interface OtelResource {

package/src/Packs.ts

@@ -7,6 +7,7 @@ import type { PlanParseError } from "@llm4ts/flow/FlowError"
 import { loadPack, type Pack } from "@llm4ts/flow/Pack"
 import { loadPatternCards, type PatternCard } from "@llm4ts/flow/Patterns"
 import type { WorkspaceError, WorkspaceShape } from "@llm4ts/flow/Workspace"
+import { settingValue } from "@llm4ts/flow/Settings"
 import {
   builtinKitsDir,
   discoverKits,
@@ -108,7 +109,7 @@ export const openPack = Effect.fn("@llm4ts/runner/Packs.openPack")(function* (op
   /** Kit tiers to search; defaults to the standard tiers around `launchDir` and `flowDir`. */
   readonly kits?: KitTierPaths
 }): Effect.fn.Return<OpenedPack, PackNotFound | WorkspaceError | PlanParseError> {
-  const reference = options.environment.LLM4TS_PACK?.trim() || defaultPackName
+  const reference = settingValue("LLM4TS_PACK", options.environment) ?? defaultPackName
   const builtinDir = builtinKitsDir(options.flowDir)
   const tiers =
     options.kits ??

package/src/PiModels.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
+import { settingGiven, settingText } from "@llm4ts/flow/Settings"
 
 /**
  * Reading `pi`'s own model config (ADR 0016). Separate from `Doctor.ts` so
@@ -29,10 +30,7 @@ export const defaultReadPiModelsJson = (): string | undefined => {
 
 export const geminiBridgePort = (
   environment: Readonly<Record<string, string | undefined>>
-): string =>
-  isSet(environment.LLM4TS_GEMINI_BRIDGE_PORT)
-    ? environment.LLM4TS_GEMINI_BRIDGE_PORT.trim()
-    : defaultGeminiBridgePort
+): string => settingText("LLM4TS_GEMINI_BRIDGE_PORT", environment) ?? defaultGeminiBridgePort
 
 /**
  * Which route the bridge serves (ADR 0037): `acp` (ADR 0016's Anthropic
@@ -46,12 +44,10 @@ export type GeminiBridgeMode =
 export const geminiBridgeMode = (
   environment: Readonly<Record<string, string | undefined>>
 ): GeminiBridgeMode => {
-  const value = (environment.LLM4TS_GEMINI_BRIDGE_MODE ?? "").trim().toLowerCase()
-  return value === "" || value === "acp"
-    ? { _tag: "Mode", mode: "acp" }
-    : value === "model"
-      ? { _tag: "Mode", mode: "model" }
-      : { _tag: "Unknown", value }
+  const given = settingGiven("LLM4TS_GEMINI_BRIDGE_MODE", environment)
+  return given._tag === "Unreadable"
+    ? { _tag: "Unknown", value: given.text.toLowerCase() }
+    : { _tag: "Mode", mode: given._tag === "Read" ? given.value : "acp" }
 }
 
 /**