@llm4ts/runner 3.2.6 → 3.4.0

package/src/AgentTree.ts

@@ -1,10 +1,18 @@
+import * as Duration from "effect/Duration"
 import type { TokenUsage } from "@llm4ts/core/Models"
 import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
 import { toolCategory } from "@llm4ts/flow/Activity"
-import { FlowEvent, cloneName } from "@llm4ts/flow/FlowEvents"
+import {
+  FlowEvent,
+  cloneName,
+  laneClosed,
+  laneOpened,
+  type LaneKind
+} from "@llm4ts/flow/FlowEvents"
 import type { TraceLine } from "@llm4ts/flow/FlowRecorder"
 import { estimateCostUsd } from "@llm4ts/flow/PriceList"
+import { settingValue } from "@llm4ts/flow/Settings"
 import { formatCount } from "./Terminal.ts"
 
 /**
@@ -26,8 +34,7 @@ export type TreeInput =
 
 export type LaneStatus = "running" | "done" | "failed"
 
-/** What a lane stands for: a story's coder (ADR 0022), a roundtable attendee (ADR 0046), or a taskforce specialist (ADR 0047). */
-export type LaneKind = "story" | "attendee" | "specialist"
+export type { LaneKind }
 
 export interface TreeLane {
   readonly id: string
@@ -236,16 +243,8 @@ export interface TreeOptions {
 export const defaultIdleAfterMs = 120_000
 
 /** `LLM4TS_IDLE_AFTER`: `90s`, `5m`, `1h` (a bare number is seconds); two minutes otherwise. */
-export const idleAfterFrom = (
-  environment: Readonly<Record<string, string | undefined>>
-): number => {
-  const match = /^(\d+)\s*(s|m|h)?$/u.exec(environment.LLM4TS_IDLE_AFTER?.trim() ?? "")
-  if (match === null) {
-    return defaultIdleAfterMs
-  }
-  const unit = match[2] === "h" ? 3_600_000 : match[2] === "m" ? 60_000 : 1_000
-  return Number(match[1]) * unit
-}
+export const idleAfterFrom = (environment: Readonly<Record<string, string | undefined>>): number =>
+  Duration.toMillis(settingValue("LLM4TS_IDLE_AFTER", environment))
 
 export const emptyTree = (options: TreeOptions = {}): TreeState => ({
   title: options.title ?? "flow",
@@ -279,8 +278,6 @@ const logged = (state: TreeState, entry: TreeLogEntry): TreeState => ({
   log: [...state.log, entry]
 })
 
-/** The stage that opens a lane: a story's, a roundtable attendee's or a taskforce specialist's (names may hold spaces). */
-const laneStage = /^(story|attendee|specialist) (.+)$/u
 const expandedTools = 20
 
 const updateLane = (
@@ -424,15 +421,9 @@ const reduceEvent = (state: TreeState, at: number, event: FlowEvent): TreeState
         }
   switch (event._tag) {
     case "StageStarted": {
-      const opened = laneStage.exec(event.stage)
-      const story = opened?.[2]
-      if (story !== undefined && event.lane === story) {
-        const kind: LaneKind =
-          opened?.[1] === "attendee"
-            ? "attendee"
-            : opened?.[1] === "specialist"
-              ? "specialist"
-              : "story"
+      const opened = laneOpened(event)
+      if (opened !== undefined) {
+        const { id: story, kind } = opened
         const fresh: TreeLane = {
           id: story,
           kind,
@@ -477,7 +468,7 @@ const reduceEvent = (state: TreeState, at: number, event: FlowEvent): TreeState
     }
     case "StageCompleted":
     case "StageFailed": {
-      if (lane !== undefined && event.stage === `${lane.kind} ${lane.id}`) {
+      if (lane !== undefined && laneClosed(event)?.kind === lane.kind) {
         const status: LaneStatus = event._tag === "StageFailed" ? "failed" : "done"
         const closed = updateLane(current, lane.id, (open) => ({
           ...open,

package/src/AgentTreeSurface.ts

@@ -5,7 +5,7 @@ import * as Ref from "effect/Ref"
 import type * as Scope from "effect/Scope"
 import * as Semaphore from "effect/Semaphore"
 import * as Stream from "effect/Stream"
-import { awaitConsumed, type FlowEventHub } from "@llm4ts/flow/FlowEvents"
+import type { FlowEventHub } from "@llm4ts/flow/FlowEvents"
 import {
   emptyTree,
   initialView,
@@ -108,17 +108,12 @@ export const makeAgentTreeHost = Effect.fn("@llm4ts/runner/AgentTreeSurface.make
   const state = yield* Ref.make(emptyTree(idleAfterMs === undefined ? {} : { idleAfterMs }))
   const view = yield* Ref.make<TreeView>(initialView)
   const active = yield* Ref.make(true)
-  const consumed = yield* Ref.make(0)
   const lock = yield* Semaphore.make(1)
 
-  const subscription = yield* hub.subscribe
-  yield* Stream.fromSubscription(subscription).pipe(
-    Stream.runForEach((event) =>
-      Effect.flatMap(Clock.currentTimeMillis, (at) =>
-        Ref.update(state, (current) => reduceTree(current, { _tag: "Event", at, event }))
-      ).pipe(Effect.andThen(Ref.update(consumed, (count) => count + 1)))
-    ),
-    Effect.forkScoped
+  const consumer = yield* hub.consume("agent tree", (event) =>
+    Effect.flatMap(Clock.currentTimeMillis, (at) =>
+      Ref.update(state, (current) => reduceTree(current, { _tag: "Event", at, event }))
+    )
   )
 
   const render = (rows: number | undefined): Effect.Effect<ReadonlyArray<string>> =>
@@ -210,7 +205,7 @@ export const makeAgentTreeHost = Effect.fn("@llm4ts/runner/AgentTreeSurface.make
 
   return {
     surface,
-    close: Effect.andThen(awaitConsumed(hub, consumed), leave(true))
+    close: Effect.andThen(consumer.caughtUp(), leave(true))
   }
 })
 

package/src/Cli.ts

@@ -3,6 +3,7 @@ import { FlowLlmError, type FlowError } from "@llm4ts/flow/FlowError"
 import { AssistantMessage } from "@llm4ts/flow/FlowEvents"
 import { collect } from "@llm4ts/core/Streaming"
 import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig"
+import { settingValue } from "@llm4ts/flow/Settings"
 import { coderFromEnvironment } from "./Connectors.ts"
 import { parseFlowArgs, readFlowPrompt, resolveFlowRepo, type ScriptUsage } from "./FlowArgs.ts"
 import { runNode } from "./FlowRunner.ts"
@@ -33,7 +34,7 @@ export const makeCliProgram = (
         workspace,
         userPrompt: prompt,
         coder,
-        verbosity: parseVerbosity(environment.LLM4TS_VERBOSITY),
+        verbosity: parseVerbosity(settingValue("LLM4TS_VERBOSITY", environment)),
         runId: timestamp.toString()
       },
       (context) =>

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,124 @@ 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 }
   }
 )
 
+/**
+ * An unknown name runs claude, with nothing said about it.
+ *
+ * @deprecated Use `seatsFromEnvironment`, which refuses an unknown name. Removed in 4.0.0.
+ */
+export const coderFromEnv = (env: Environment = process.env): CliConnectorConfig => {
+  const requested = settingValue("LLM4TS_CODER", env)
+  return (requested === undefined ? claude : coderFor(requested)) ?? claude
+}
+
+/**
+ * `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 +341,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}`)
       }