@llm4ts/runner 3.3.0 → 4.0.0

package/src/Connectors.ts

@@ -4,10 +4,22 @@ import * as Redacted from "effect/Redacted"
 import {
   ApiConnectorConfig,
   CliConnectorConfig,
-  type ConnectorConfig
+  type ConnectorConfig,
+  type ConnectorConfigOf
 } from "@llm4ts/core/ConnectorConfig"
-import { ConnectorIds, connectorDefaultBaseUrl } from "@llm4ts/core/Models"
+import {
+  ConnectorIds,
+  apiProviderConnector,
+  coderConnector,
+  coderNames,
+  connectorDefaultBaseUrl,
+  connectorRow,
+  connectorTable,
+  offeredApiProviderNames,
+  type ConnectorName
+} from "@llm4ts/core/Models"
 import { runStateDeniedPaths } from "@llm4ts/flow/RunState"
+import { settingText, settingValue } from "@llm4ts/flow/Settings"
 import { ScriptUsage } from "./FlowArgs.ts"
 
 export const claude = CliConnectorConfig.make({
@@ -53,12 +65,12 @@ export const opencode = CliConnectorConfig.make({
 
 export const lmStudio = ApiConnectorConfig.make({
   connectorId: ConnectorIds.LmStudio,
-  baseUrl: "http://localhost:1234/v1"
+  baseUrl: connectorTable.LmStudio.baseUrl
 })
 
 export const mlxLm = ApiConnectorConfig.make({
   connectorId: ConnectorIds.MlxLm,
-  baseUrl: "http://localhost:8080"
+  baseUrl: connectorTable.MlxLm.baseUrl
 })
 
 export const openAI = ApiConnectorConfig.make({
@@ -82,6 +94,26 @@ export const mock = ApiConnectorConfig.make({
   model: "mock"
 })
 
+// A connector without a preset here does not compile.
+const presets: { readonly [K in ConnectorName]: ConnectorConfigOf<K> } = {
+  OpenAI: openAI,
+  Anthropic: anthropic,
+  GeminiApi: geminiApi,
+  LmStudio: lmStudio,
+  Ollama: ollama,
+  MlxLm: mlxLm,
+  ClaudeCli: claude,
+  GeminiCli: gemini,
+  OpenCode: opencode,
+  Codex: codex,
+  Copilot: CliConnectorConfig.make({ connectorId: ConnectorIds.Copilot }),
+  Pi: pi,
+  AntigravityCli: antigravity,
+  Grok: grok,
+  Cursor: cursor,
+  Mock: mock
+}
+
 export function withModel(config: CliConnectorConfig, model: string): CliConnectorConfig
 export function withModel(config: ApiConnectorConfig, model: string): ApiConnectorConfig
 export function withModel(
@@ -134,16 +166,12 @@ const environmentApiKey = (
   config: ApiConnectorConfig,
   environment: Readonly<Record<string, string | undefined>>
 ): string | undefined => {
-  switch (config.connectorId.value) {
-    case "openai":
-      return environment.OPENAI_API_KEY
-    case "anthropic":
-      return environment.ANTHROPIC_API_KEY
-    case "gemini-api":
-      return environment.GEMINI_API_KEY ?? environment.GOOGLE_API_KEY
-    default:
-      return undefined
-  }
+  const row = connectorRow(config.connectorId)
+  return row?.kind === "Api"
+    ? row.credentialVariables
+        .map((variable) => environment[variable])
+        .find((value) => value !== undefined)
+    : undefined
 }
 
 export const enrichApiConnector = (
@@ -163,9 +191,6 @@ export const enrichApiConnector = (
   })
 }
 
-const switchedOn = (value: string | undefined): boolean =>
-  value !== undefined && ["1", "true", "on", "yes"].includes(value.trim().toLowerCase())
-
 export const prepareConnector = (
   config: ConnectorConfig,
   workDir: string,
@@ -179,7 +204,7 @@ export const prepareConnector = (
         workingDir: workDir,
         // `LLM4TS_ISOLATED=1` asks every CLI seat of the run to leave the
         // repository's own harness material unloaded (ADR 0029).
-        ...(switchedOn(environment.LLM4TS_ISOLATED) ? { isolated: true } : {}),
+        ...(settingValue("LLM4TS_ISOLATED", environment) ? { isolated: true } : {}),
         // Every CLI seat keeps out of the run's own state unless the seat
         // (or the run) says otherwise; the connector maps it to a deny
         // rule where its harness has one (`capabilities.pathDeny`).
@@ -188,110 +213,114 @@ export const prepareConnector = (
 
 /** The API provider a name stands for (`LLM4TS_PROVIDER`, a roster executor's `harness`). */
 export const apiPresetFor = (name: string): ApiConnectorConfig | undefined => {
-  switch (name.trim().toLowerCase()) {
-    case "mock":
-      return mock
-    case "openai":
-      return openAI
-    case "anthropic":
-      return anthropic
-    case "gemini":
-    case "gemini-api":
-      return geminiApi
-    case "lm-studio":
-    case "lmstudio":
-      return lmStudio
-    case "ollama":
-      return ollama
-    case "mlx-lm":
-    case "mlxlm":
-    case "mlx":
-      return mlxLm
-    default:
-      return undefined
-  }
+  const connector = apiProviderConnector(name.trim().toLowerCase())
+  return connector === undefined ? undefined : presets[connector]
 }
 
-export const apiConnectorFromEnvironment = Effect.fn(
-  "@llm4ts/runner/Connectors.apiConnectorFromEnvironment"
-)(function* (
-  environment: Readonly<Record<string, string | undefined>> = process.env
+const apiConnectorNamed = Effect.fnUntraced(function* (
+  named: string,
+  model: string | undefined
 ): Effect.fn.Return<ApiConnectorConfig, ScriptUsage> {
-  const provider = environment.LLM4TS_PROVIDER?.trim().toLowerCase() ?? "mock"
+  const provider = named.toLowerCase()
   const preset = apiPresetFor(provider)
   if (preset === undefined) {
     return yield* ScriptUsage.make({
-      message:
-        `unknown LLM4TS_PROVIDER '${provider}'; expected ` +
-        "mock|openai|anthropic|gemini|lm-studio|ollama|mlx-lm"
+      message: `unknown LLM4TS_PROVIDER '${provider}'; expected ${offeredApiProviderNames.join("|")}`
     })
   }
-  const model = environment.LLM4TS_MODEL?.trim()
-  if (provider !== "mock" && (model === undefined || model.length === 0)) {
+  if (provider !== "mock" && model === undefined) {
     return yield* ScriptUsage.make({
       message: `LLM4TS_MODEL is required for provider '${provider}' (e.g. LLM4TS_MODEL=gpt-4o-mini)`
     })
   }
-  return model === undefined || model.length === 0 ? preset : withModel(preset, model)
+  return model === undefined ? preset : withModel(preset, model)
 })
 
-// Every coding CLI, with the names an operator may write for it. The
-// connector's own id is always one of them, derived rather than repeated:
-// `gemini-cli` is the string llm4ts prints in events, traces and errors,
-// so it is the name an operator has actually seen — it must not resolve to
-// a different vendor's CLI.
-const coderAliases: ReadonlyArray<readonly [CliConnectorConfig, ReadonlyArray<string>]> = [
-  [claude, ["claude"]],
-  [codex, ["codex"]],
-  [gemini, ["gemini"]],
-  [pi, ["pi"]],
-  [antigravity, ["agy", "antigravity"]],
-  [grok, ["grok"]],
-  [cursor, ["cursor"]],
-  [opencode, ["opencode"]]
-]
-
-const coders = new Map<string, CliConnectorConfig>(
-  coderAliases.flatMap(([preset, aliases]) =>
-    [...aliases, preset.connectorId.value].map((name) => [name, preset] as const)
+export const apiConnectorFromEnvironment = Effect.fn(
+  "@llm4ts/runner/Connectors.apiConnectorFromEnvironment"
+)(function* (
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): Effect.fn.Return<ApiConnectorConfig, ScriptUsage> {
+  return yield* apiConnectorNamed(
+    settingText("LLM4TS_PROVIDER", environment) ?? "mock",
+    settingValue("LLM4TS_MODEL", environment)
   )
-)
+})
 
-export const coderIds: ReadonlyArray<string> = Object.freeze([...coders.keys()].sort())
+export const coderIds: ReadonlyArray<string> = Object.freeze([...coderNames].sort())
 
-export const coderFor = (name: string): CliConnectorConfig | undefined =>
-  coders.get(name.trim().toLowerCase())
+export const coderFor = (name: string): CliConnectorConfig | undefined => {
+  const connector = coderConnector(name.trim().toLowerCase())
+  return connector === undefined ? undefined : presets[connector]
+}
 
-// Unchecked: an unrecognized name falls back to claude, which silently
-// runs a CLI the operator did not ask for. Prefer coderFromEnvironment,
-// which refuses and names the coders it knows.
-export const coderFromEnv = (
-  env: Readonly<Record<string, string | undefined>> = process.env
-): CliConnectorConfig => {
-  const requested = (env.LLM4TS_CODER ?? "").trim()
-  return (requested.length === 0 ? claude : coderFor(requested)) ?? claude
+export interface SeatDefaults {
+  /** The coder when `LLM4TS_CODER` is unset; claude when omitted. */
+  readonly coder?: CliConnectorConfig
+  /** The reasoner when `LLM4TS_REASONER` is unset; the coder seat when omitted. */
+  readonly reasoner?: CliConnectorConfig
 }
 
-// The checked reading, matching apiConnectorFromEnvironment above: an
-// unset variable is the claude default, and an unknown one is a usage
-// error rather than a different coder than the one asked for.
-export const coderFromEnvironment = Effect.fn("@llm4ts/runner/Connectors.coderFromEnvironment")(
-  function* (
-    environment: Readonly<Record<string, string | undefined>> = process.env
-  ): Effect.fn.Return<CliConnectorConfig, ScriptUsage> {
-    const requested = (environment.LLM4TS_CODER ?? "").trim()
-    if (requested.length === 0) {
-      return claude
-    }
-    const preset = coderFor(requested)
-    return preset === undefined
-      ? yield* ScriptUsage.make({
-          message: `unknown LLM4TS_CODER '${requested}'; expected ${coderIds.join("|")}`
+export interface Seats {
+  readonly coder: CliConnectorConfig
+  readonly reasoning: CliConnectorConfig
+}
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+const namedSeat = (
+  variable: "LLM4TS_CODER" | "LLM4TS_REASONER",
+  environment: Environment
+): Effect.Effect<CliConnectorConfig | undefined, ScriptUsage> => {
+  const requested = settingText(variable, environment)
+  if (requested === undefined) {
+    return Effect.succeed(undefined)
+  }
+  const preset = coderFor(requested)
+  return preset === undefined
+    ? Effect.fail(
+        ScriptUsage.make({
+          message: `unknown ${variable} '${requested}'; expected ${coderIds.join("|")}`
         })
-      : preset
+      )
+    : Effect.succeed(preset)
+}
+
+/**
+ * The coder and reasoning seats of a flow that runs both, from `LLM4TS_CODER`
+ * and `LLM4TS_REASONER`. An unknown name is a usage error naming the accepted
+ * names, never another agent. A flow with one seat reads that one alone
+ * (`coderFromEnvironment`, `reasonerFromEnvironment`).
+ */
+export const seatsFromEnvironment = Effect.fn("@llm4ts/runner/Connectors.seatsFromEnvironment")(
+  function* (
+    defaults: SeatDefaults = {},
+    environment: Environment = process.env
+  ): Effect.fn.Return<Seats, ScriptUsage> {
+    const coder = (yield* namedSeat("LLM4TS_CODER", environment)) ?? defaults.coder ?? claude
+    const reasoner = yield* namedSeat("LLM4TS_REASONER", environment)
+    return { coder, reasoning: reasoner ?? defaults.reasoner ?? coder }
   }
 )
 
+/**
+ * `LLM4TS_CODER` alone, for a flow that runs no separate reasoning seat. A
+ * flow answers only for the seats it uses: a bad `LLM4TS_REASONER` is not
+ * this flow's to refuse.
+ */
+export const coderFromEnvironment = (
+  environment: Environment = process.env,
+  fallback: CliConnectorConfig = claude
+): Effect.Effect<CliConnectorConfig, ScriptUsage> =>
+  Effect.map(namedSeat("LLM4TS_CODER", environment), (coder) => coder ?? fallback)
+
+/** `LLM4TS_REASONER` alone, for a flow that edits nothing. */
+export const reasonerFromEnvironment = (
+  environment: Environment = process.env,
+  fallback: CliConnectorConfig = claude
+): Effect.Effect<CliConnectorConfig, ScriptUsage> =>
+  Effect.map(namedSeat("LLM4TS_REASONER", environment), (reasoner) => reasoner ?? fallback)
+
 /**
  * The judgment seat from the environment (ADR 0017): `LLM4TS_JUDGMENT_PROVIDER`
  * names an API provider the way `LLM4TS_PROVIDER` does, `LLM4TS_JUDGMENT_MODEL`
@@ -302,13 +331,8 @@ export const judgmentConnectorFromEnvironment = Effect.fn(
 )(function* (
   environment: Readonly<Record<string, string | undefined>> = process.env
 ): Effect.fn.Return<ApiConnectorConfig | undefined, ScriptUsage> {
-  const provider = environment.LLM4TS_JUDGMENT_PROVIDER?.trim()
-  if (provider === undefined || provider.length === 0) {
-    return undefined
-  }
-  return yield* apiConnectorFromEnvironment({
-    ...environment,
-    LLM4TS_PROVIDER: provider,
-    LLM4TS_MODEL: environment.LLM4TS_JUDGMENT_MODEL
-  })
+  const provider = settingText("LLM4TS_JUDGMENT_PROVIDER", environment)
+  return provider === undefined
+    ? undefined
+    : yield* apiConnectorNamed(provider, settingValue("LLM4TS_JUDGMENT_MODEL", environment))
 })

package/src/Doctor.ts

@@ -1,8 +1,9 @@
 import * as Effect from "effect/Effect"
 import type { ConnectorKind, HealthStatus } from "@llm4ts/core/Models"
-import { ConnectorIds } from "@llm4ts/core/Models"
+import { ConnectorIds, credentialVariables } from "@llm4ts/core/Models"
 import type { ConnectorRegistryShape } from "@llm4ts/core/ConnectorRegistry"
 import { nodePreflightReport, type NodePreflightReport } from "@llm4ts/flow/NodePreflight"
+import { settingText, settingValue } from "@llm4ts/flow/Settings"
 import { nodeFlowRunnerDependencies } from "./FlowRunner.ts"
 import { nodePlainFileStore } from "./NodePlainFileStore.ts"
 import { nodeProcessExecutor } from "./NodeProcessExecutor.ts"
@@ -15,13 +16,6 @@ import {
 import { systemAdminPolicies, systemPolicyProblem } from "./NodeGeminiModelBridge.ts"
 import { otelConfig, otelDoctorLine, probeOtelEndpoint, type OtelConfig } from "./Otel.ts"
 
-const credentialKeys = [
-  "OPENAI_API_KEY",
-  "ANTHROPIC_API_KEY",
-  "GEMINI_API_KEY",
-  "GOOGLE_API_KEY"
-] as const
-
 /**
  * How far a connector's health was verified: `"auth"` means the CLI's own
  * login check answered (`authStatus` is its word); `"version"` means only
@@ -133,7 +127,7 @@ const wrap = (text: string, width: number, indent: string): ReadonlyArray<string
 }
 
 const selectedCoder = (environment: Readonly<Record<string, string | undefined>>): string =>
-  environment.LLM4TS_CODER ?? "claude (default)"
+  settingText("LLM4TS_CODER", environment) ?? "claude (default)"
 
 // Re-exported so `@llm4ts/runner/Doctor` stays the one place callers look
 // for pi-config questions, while the parsing itself has no dependency on
@@ -161,7 +155,7 @@ export const geminiBridgePrerequisites = (
   environment: Readonly<Record<string, string | undefined>>,
   modelsJson: string | undefined
 ): PrerequisiteReport | undefined => {
-  if (!truthy(environment.LLM4TS_GEMINI_BRIDGE)) {
+  if (!settingValue("LLM4TS_GEMINI_BRIDGE", environment)) {
     return undefined
   }
   const port = bridgePort(environment)
@@ -254,7 +248,11 @@ export const geminiModelModePrerequisites = (
   systemPolicies: ReadonlyArray<string>
 ): PrerequisiteReport | undefined => {
   const mode = geminiBridgeMode(environment)
-  if (!truthy(environment.LLM4TS_GEMINI_BRIDGE) || mode._tag !== "Mode" || mode.mode !== "model") {
+  if (
+    !settingValue("LLM4TS_GEMINI_BRIDGE", environment) ||
+    mode._tag !== "Mode" ||
+    mode.mode !== "model"
+  ) {
     return undefined
   }
   const detail = [
@@ -324,7 +322,7 @@ export const collectDoctorReport = (
       const lines: Array<string> = []
       lines.push("")
       lines.push("credentials:")
-      for (const key of credentialKeys) {
+      for (const key of credentialVariables) {
         const value = environment[key]
         lines.push(`  ${value === undefined || value.length === 0 ? "✖" : "✔"} ${key}`)
       }

package/src/EventPresentation.ts

@@ -0,0 +1,167 @@
+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" },
+  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.