@llm4ts/runner 2.2.1 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
     "./FlowRunner": "./dist/FlowRunner.js",
     "./Kits": "./dist/Kits.js",
     "./McpStdio": "./dist/McpStdio.js",
+    "./NodeGeminiAcpBridge": "./dist/NodeGeminiAcpBridge.js",
     "./NodeHttpClient": "./dist/NodeHttpClient.js",
     "./NodeGeminiCliExecutor": "./dist/NodeGeminiCliExecutor.js",
     "./NodePlainFileStore": "./dist/NodePlainFileStore.js",
@@ -30,6 +31,7 @@
     "./NodeWorkspace": "./dist/NodeWorkspace.js",
     "./NodeRuntime": "./dist/NodeRuntime.js",
     "./Packs": "./dist/Packs.js",
+    "./PiModels": "./dist/PiModels.js",
     "./ReviewFingerprint": "./dist/ReviewFingerprint.js",
     "./Terminal": "./dist/Terminal.js",
     "./TerminalInteraction": "./dist/TerminalInteraction.js",
@@ -59,8 +61,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.2.1",
-    "@llm4ts/flow": "2.2.1"
+    "@llm4ts/core": "2.3.1",
+    "@llm4ts/flow": "2.3.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"

package/src/Doctor.ts

@@ -3,6 +3,11 @@ import type { HealthStatus } from "@llm4ts/core/Models"
 import { ConnectorIds } from "@llm4ts/core/Models"
 import type { ConnectorRegistryShape } from "@llm4ts/core/ConnectorRegistry"
 import { nodeFlowRunnerDependencies } from "./FlowRunner.ts"
+import {
+  defaultReadPiModelsJson as readPiModels,
+  geminiBridgePort as bridgePort,
+  piModelsConfig as parsePiModels
+} from "./PiModels.ts"
 
 const credentialKeys = [
   "OPENAI_API_KEY",
@@ -28,6 +33,8 @@ export interface PrerequisiteReport {
   readonly satisfied: boolean
   readonly summary: string
   readonly hint?: string
+  /** Extra lines rendered under the summary, already indented relative to it. */
+  readonly detail?: ReadonlyArray<string>
 }
 
 /**
@@ -98,9 +105,111 @@ const wrap = (text: string, width: number, indent: string): ReadonlyArray<string
 const selectedCoder = (environment: Readonly<Record<string, string | undefined>>): string =>
   environment.LLM4TS_CODER ?? "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
+// this module (the flow runner needs it, and Doctor imports the runner).
+export {
+  bridgeModelProblem,
+  bridgeModelRefs,
+  defaultGeminiBridgePort,
+  defaultReadPiModelsJson,
+  geminiBridgePort,
+  piModelRefs,
+  piModelsConfig,
+  resolveBridgeModel,
+  type BridgeModelResolution,
+  type PiModelRef,
+  type PiModelsConfig
+} from "./PiModels.ts"
+
+/**
+ * Whether pi's custom-provider config points at this machine's Gemini ACP
+ * bridge — detect-and-report only, never auto-fixed (ADR 0016). `undefined`
+ * means the check doesn't apply: nothing asked for the bridge.
+ */
+export const geminiBridgePrerequisites = (
+  environment: Readonly<Record<string, string | undefined>>,
+  modelsJson: string | undefined
+): PrerequisiteReport | undefined => {
+  if (!truthy(environment.LLM4TS_GEMINI_BRIDGE)) {
+    return undefined
+  }
+  const port = bridgePort(environment)
+  const needle = `127.0.0.1:${port}`
+  const hint =
+    `add a custom provider to ~/.pi/agent/models.json with baseUrl ` +
+    `"http://${needle}" so pi draws inference from the gemini-cli bridge instead ` +
+    `of a model API key (ADR 0016) — llm4ts never writes this file for you.`
+  if (modelsJson === undefined) {
+    return { satisfied: false, summary: "~/.pi/agent/models.json not found", hint }
+  }
+  const { refs, problems } = parsePiModels(modelsJson, port)
+  // pi rejects the whole file on any schema error, so a well-formed bridge
+  // entry sitting beside a bad one is still not loaded. Report that first:
+  // every model below would otherwise look available while pi sees none.
+  if (problems.length > 0) {
+    return {
+      satisfied: false,
+      summary: "~/.pi/agent/models.json fails pi's schema, so pi loads none of it",
+      hint:
+        `fix the errors below and re-check with \`pi --list-models\`. Each models ` +
+        `entry must be an object with a string id ({ "id": "gemini-2.5-pro" }), not ` +
+        `a bare string.`,
+      detail: problems.map((problem) => `  ${problem}`)
+    }
+  }
+  const bridged = refs.filter((entry) => entry.bridged)
+  const usable = bridged.filter((entry) => entry.authConfigured).map((entry) => entry.ref)
+  if (usable.length > 0) {
+    return {
+      satisfied: true,
+      summary: `a provider in ~/.pi/agent/models.json points at ${needle}`,
+      detail: [
+        "bridge models — pass one as LLM4TS_GEMINI_BRIDGE_MODEL (pi's --model):",
+        ...usable.map((ref) => `  ${ref}`)
+      ]
+    }
+  }
+  // Loaded but hidden: pi keeps a keyless provider's models out of `--model`
+  // and `--list-models`. The bridge authenticates as gemini, not as pi, so
+  // any placeholder satisfies this.
+  if (bridged.length > 0) {
+    return {
+      satisfied: false,
+      summary: `the provider pointing at ${needle} configures no apiKey, so pi hides its models`,
+      hint:
+        `give that provider any placeholder apiKey (the bridge never checks it — ` +
+        `gemini's own OAuth session supplies the credential), or run \`pi /login\` ` +
+        `for it.`,
+      detail: bridged.map((entry) => `  ${entry.ref}`)
+    }
+  }
+  // A provider can point at the bridge and still list no models: pi resolves
+  // `--model` against that list, so the run fails with "Model not found"
+  // while a check that only greps for the port reports success.
+  const pointed = modelsJson.includes(needle)
+  const others = refs.map((entry) => entry.ref)
+  return {
+    satisfied: false,
+    summary: pointed
+      ? `a provider in ~/.pi/agent/models.json points at ${needle} but lists no models`
+      : `no provider in ~/.pi/agent/models.json points at ${needle}`,
+    hint,
+    ...(others.length === 0
+      ? {}
+      : {
+          detail: [
+            "models pi can resolve today, none of them bridged:",
+            ...others.map((ref) => `  ${ref}`)
+          ]
+        })
+  }
+}
+
 export const makeDoctorProgram = (
   registry: ConnectorRegistryShape = nodeFlowRunnerDependencies().registry,
-  environment: Readonly<Record<string, string | undefined>> = process.env
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  readPiModelsJson: () => string | undefined = readPiModels
 ): Effect.Effect<string> =>
   Effect.map(registry.healthCheckAll, (statuses) => {
     const lines: Array<string> = []
@@ -128,13 +237,24 @@ export const makeDoctorProgram = (
         (id) =>
           id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value
       )
-    if (geminiRelevant) {
-      const gemini = geminiPrerequisites(environment)
+    const bridge = geminiBridgePrerequisites(environment, readPiModelsJson())
+    if (geminiRelevant || bridge !== undefined) {
       lines.push("")
       lines.push("prerequisites:")
-      lines.push(`  ${gemini.satisfied ? "✔" : "?"} gemini: ${gemini.summary}`)
-      if (gemini.hint !== undefined) {
-        lines.push(...wrap(gemini.hint, 78, "      "))
+      const pushReport = (label: string, report: PrerequisiteReport): void => {
+        lines.push(`  ${report.satisfied ? "✔" : "?"} ${label}: ${report.summary}`)
+        if (report.hint !== undefined) {
+          lines.push(...wrap(report.hint, 78, "      "))
+        }
+        for (const line of report.detail ?? []) {
+          lines.push(`      ${line}`)
+        }
+      }
+      if (geminiRelevant) {
+        pushReport("gemini", geminiPrerequisites(environment))
+      }
+      if (bridge !== undefined) {
+        pushReport("pi-gemini-bridge", bridge)
       }
     }
 

package/src/FlowRunner.ts

@@ -11,7 +11,16 @@ import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
 import type { TemporaryFilesShape } from "@llm4ts/core/TemporaryFiles"
 import type { GeminiCliExecutorShape } from "@llm4ts/core/providers/GeminiCliProvider"
 import { createConnectorRegistry } from "@llm4ts/core/providers/ConnectorFactories"
+import { ConnectorIds } from "@llm4ts/core/Models"
+import { ProviderError } from "@llm4ts/core/Errors"
 import { makeCostTracker, type CostTracker } from "@llm4ts/flow/CostTracker"
+import { runGeminiAcpBridge } from "./NodeGeminiAcpBridge.ts"
+import {
+  bridgeModelProblem,
+  defaultReadPiModelsJson,
+  geminiBridgePort,
+  resolveBridgeModel
+} from "./PiModels.ts"
 import { checkCostBudget, makeCostRecord, type CostBudget } from "@llm4ts/flow/CostLedger"
 import { FlowLlmError, describeFlowError, type FlowError } from "@llm4ts/flow/FlowError"
 import {
@@ -50,6 +59,8 @@ export interface FlowRunnerDependencies {
   readonly registry: ConnectorRegistryShape
   readonly process: ProcessExecutorShape
   readonly files: PlainFileStoreShape
+  /** pi's own model config (ADR 0016), injectable so a test never reads $HOME. */
+  readonly readPiModelsJson?: () => string | undefined
 }
 
 export interface NodeConnectorDependencies {
@@ -99,6 +110,68 @@ export interface FlowRunnerBundle {
   readonly tracker: CostTracker
 }
 
+const truthy = (value: string | undefined): boolean =>
+  value !== undefined && ["1", "true", "yes"].includes(value.trim().toLowerCase())
+
+const isPiSeat = (config: ConnectorConfig | undefined): config is CliConnectorConfig =>
+  config instanceof CliConnectorConfig && config.connectorId.value === ConnectorIds.Pi.value
+
+/**
+ * Start the ADR 0016 bridge for a `pi`-coder run, scoped to that run, and
+ * return the mapping that points pi's seats at it.
+ *
+ * Opting in with `LLM4TS_GEMINI_BRIDGE` but leaving pi unable to reach the
+ * bridge is the failure this whole feature exists to avoid, so an
+ * unresolvable model fails the run here rather than surfacing as pi's own
+ * "No API key found" several layers down. A seat that already names a model
+ * is left alone: an explicit choice outranks the default.
+ */
+const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats")(function* (
+  options: FlowRunnerOptions,
+  dependencies: FlowRunnerDependencies,
+  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)) {
+    return identity
+  }
+  // The reasoning seat defaults to the coder, so a pi coder makes this a pi
+  // run even when nothing else names pi.
+  const seats = [options.coder, options.reasoning, ...(options.reviewers ?? [])]
+  if (!seats.some(isPiSeat)) {
+    return identity
+  }
+
+  const port = geminiBridgePort(environment)
+  const readPiModelsJson = dependencies.readPiModelsJson ?? defaultReadPiModelsJson
+  const resolution = resolveBridgeModel(
+    readPiModelsJson(),
+    port,
+    environment.LLM4TS_GEMINI_BRIDGE_MODEL
+  )
+  const problem = bridgeModelProblem(resolution, port)
+  if (problem !== undefined || resolution._tag !== "Resolved") {
+    return yield* FlowLlmError.from(
+      ProviderError.make({ message: problem ?? "no bridge model available" })
+    )
+  }
+  const model = resolution.model
+
+  yield* runGeminiAcpBridge({
+    port: Number(port),
+    cwd: options.workDir,
+    executor: dependencies.process,
+    ...(environment.LLM4TS_GEMINI_MODEL === undefined
+      ? {}
+      : { model: environment.LLM4TS_GEMINI_MODEL })
+  }).pipe(Effect.mapError(FlowLlmError.from))
+
+  return (config: ConnectorConfig): ConnectorConfig =>
+    isPiSeat(config) && config.model === undefined
+      ? CliConnectorConfig.make({ ...config, model })
+      : config
+})
+
 export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeContext")(function* (
   options: FlowRunnerOptions,
   dependencies: FlowRunnerDependencies
@@ -107,6 +180,13 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   const tracker = yield* makeCostTracker()
   yield* tracker.consume(events)
   const reasoning = defaultReasoningConfig(options.coder, options.reasoning)
+  // Bound to this run's scope: the bridge subprocess and its server go away
+  // with the run, matching every other long-lived subprocess here (ADR 0016).
+  const bridged = yield* geminiBridgeSeats(
+    options,
+    dependencies,
+    options.environment ?? process.env
+  )
   // Every seat retries transient provider failures and flaky streams (an
   // empty response or malformed tool call), announcing each attempt on the
   // run's events. Without the wrapper one hiccup from a CLI agent failed the
@@ -157,10 +237,12 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
     Scope.Scope
   > {
     const environment = options.environment ?? process.env
-    const coder = yield* resolveSeat(prepareConnector(options.coder, workDir, environment))
-    const reasoningService = yield* resolveSeat(prepareConnector(reasoning, workDir, environment))
+    const coder = yield* resolveSeat(prepareConnector(bridged(options.coder), workDir, environment))
+    const reasoningService = yield* resolveSeat(
+      prepareConnector(bridged(reasoning), workDir, environment)
+    )
     const reviewers = yield* Effect.forEach(options.reviewers ?? [], (configuration) =>
-      resolveSeat(prepareConnector(configuration, workDir, environment))
+      resolveSeat(prepareConnector(bridged(configuration), workDir, environment))
     )
     return { coder, reasoning: reasoningService, reviewers }
   })