@llm4ts/runner 3.3.0 → 4.0.0

package/src/FlowRunner.ts

@@ -27,6 +27,8 @@ 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, unreadableEnvironment, type Environment } from "@llm4ts/flow/Settings"
+import { ScriptUsage } from "./FlowArgs.ts"
 import { runGeminiAcpBridge } from "./NodeGeminiAcpBridge.ts"
 import { runGeminiModelBridge } from "./NodeGeminiModelBridge.ts"
 import {
@@ -51,7 +53,7 @@ import {
   type FlowError
 } from "@llm4ts/flow/FlowError"
 import {
-  defaultDrainTimeout,
+  type DrainReport,
   FlowEvents,
   FlowEventsValues,
   Info,
@@ -119,9 +121,9 @@ import {
   formatDurationMs,
   makeTerminalSurface,
   parseVerbosity,
-  type TerminalSurface,
-  type Verbosity
+  type TerminalSurface
 } from "./Terminal.ts"
+import type { Verbosity } from "./EventPresentation.ts"
 
 const describeSeat = (config: ConnectorConfig): string => {
   const model = config.model === undefined ? "" : ` (${config.model})`
@@ -264,12 +266,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 +285,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 +300,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 +318,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 +334,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 +362,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 +515,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 +572,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 +582,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 +977,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 +1009,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 +1049,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 +1136,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 +1166,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 +1241,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 &&
@@ -1267,11 +1254,24 @@ const runOutcomeOf = <A, E>(exit: Exit.Exit<A, E>): RunOutcome =>
       ? "interrupted"
       : "failed"
 
+/**
+ * The shell's launch check for a run that did not come through it: an
+ * environment value the settings registry cannot read stops the run before
+ * anything starts, instead of reading as unset.
+ */
+const requireReadableEnvironment = (environment: Environment): Effect.Effect<void, ScriptUsage> => {
+  const problems = unreadableEnvironment(environment)
+  return problems.length === 0
+    ? Effect.void
+    : Effect.fail(ScriptUsage.make({ message: problems.join("\n") }))
+}
+
 export const runEmbedded = Effect.fn("@llm4ts/runner/FlowRunner.runEmbedded")(function* <A, E, R>(
   options: FlowRunnerOptions,
   body: (context: FlowContextShape) => Effect.Effect<A, E, R>,
   dependencies: FlowRunnerDependencies = nodeFlowRunnerDependencies()
-): Effect.fn.Return<A, E | FlowError, R | Scope.Scope> {
+): Effect.fn.Return<A, E | FlowError | ScriptUsage, R | Scope.Scope> {
+  yield* requireReadableEnvironment(options.environment ?? process.env)
   const bundle = yield* makeFlowRunnerContext(options, dependencies)
   return yield* runWithBundle(bundle, options, body, dependencies)
 })
@@ -1279,7 +1279,7 @@ export const runEmbedded = Effect.fn("@llm4ts/runner/FlowRunner.runEmbedded")(fu
 export const runNode = <A, E, R>(
   options: FlowRunnerOptions,
   body: (context: FlowContextShape) => Effect.Effect<A, E, R>
-): Effect.Effect<A, E | FlowError, R> => Effect.scoped(runEmbedded(options, body))
+): Effect.Effect<A, E | FlowError | ScriptUsage, R> => Effect.scoped(runEmbedded(options, body))
 
 const mainErrorMessage = (error: unknown): string =>
   error instanceof Error && error.message.length > 0 ? error.message : String(error)
@@ -1359,9 +1359,15 @@ const processSignals: SignalSource = {
   exit: (code) => process.exit(code)
 }
 
+/**
+ * A flow script's entry point. An environment value the settings registry
+ * cannot read stops it before `program` starts, as `llm4ts run` would have;
+ * any failure is printed and exits 1.
+ */
 export const runFlowMain = <E>(program: Effect.Effect<void, E>): void => {
   const fiber = Effect.runFork(
-    program.pipe(
+    requireReadableEnvironment(process.env).pipe(
+      Effect.andThen(program),
       Effect.match({
         onFailure: (error) =>
           Effect.sync(() => {

package/src/NodeGeminiCliExecutor.ts

@@ -1,3 +1,4 @@
+// @internal: Gemini CLI executor wired by FlowRunner
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Stream from "effect/Stream"
@@ -19,6 +20,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 +51,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 +79,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 +93,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 +115,7 @@ export const makeNodeGeminiCliExecutor = (
             ([environment, args]) =>
               executor
                 .runStreamingWithStdin(
-                  ["gemini", ...args],
+                  [executable, ...args],
                   context.cwd ?? process.cwd(),
                   environment,
                   prompt

package/src/NodeGeminiModelBridge.ts

@@ -1,3 +1,4 @@
+// @internal: Gemini bridge wiring for FlowRunner, Doctor and the bridge server
 import { existsSync, readdirSync } from "node:fs"
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { join } from "node:path"
@@ -34,6 +35,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 +135,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/NodeHttpClient.ts

@@ -1,3 +1,4 @@
+// @internal: the Node HTTP client FlowRunner provides
 import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"

package/src/Otel.ts

@@ -1,3 +1,4 @@
+// @internal: OpenTelemetry export wired by FlowRunner and Doctor
 // OpenTelemetry export (ADR 0026): Effect's own OTLP tracer and metrics
 // exporters over core's fetch client, so a run can show up in Phoenix,
 // Langfuse, SigNoz or any collector with no SDK and no new dependency.
@@ -12,6 +13,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 +25,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 +34,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 +50,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/Package.ts

@@ -1,3 +1,4 @@
+// @internal: the runner's own version stamp
 import { createRequire } from "node:module"
 import * as Schema from "effect/Schema"
 

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" }
 }
 
 /**