@llm4ts/runner 2.3.0 → 2.4.0

package/src/Doctor.ts

@@ -1,11 +1,13 @@
-import { readFileSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
 import * as Effect from "effect/Effect"
 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",
@@ -31,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>
 }
 
 /**
@@ -101,20 +105,22 @@ const wrap = (text: string, width: number, indent: string): ReadonlyArray<string
 const selectedCoder = (environment: Readonly<Record<string, string | undefined>>): string =>
   environment.LLM4TS_CODER ?? "claude (default)"
 
-export const defaultGeminiBridgePort = "8731"
-
-/**
- * `~/.pi/agent/models.json` (ADR 0016). Read for reporting only — this file
- * belongs to `pi`, outside llm4ts's package graph, and llm4ts never writes
- * it. Missing is not an error here: the file simply doesn't exist yet.
- */
-export const defaultReadPiModelsJson = (): string | undefined => {
-  try {
-    return readFileSync(join(homedir(), ".pi", "agent", "models.json"), "utf8")
-  } catch {
-    return undefined
-  }
-}
+// 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
@@ -128,9 +134,7 @@ export const geminiBridgePrerequisites = (
   if (!truthy(environment.LLM4TS_GEMINI_BRIDGE)) {
     return undefined
   }
-  const port = isSet(environment.LLM4TS_GEMINI_BRIDGE_PORT)
-    ? environment.LLM4TS_GEMINI_BRIDGE_PORT.trim()
-    : defaultGeminiBridgePort
+  const port = bridgePort(environment)
   const needle = `127.0.0.1:${port}`
   const hint =
     `add a custom provider to ~/.pi/agent/models.json with baseUrl ` +
@@ -139,22 +143,73 @@ export const geminiBridgePrerequisites = (
   if (modelsJson === undefined) {
     return { satisfied: false, summary: "~/.pi/agent/models.json not found", hint }
   }
-  return modelsJson.includes(needle)
-    ? {
-        satisfied: true,
-        summary: `a provider in ~/.pi/agent/models.json points at ${needle}`
-      }
-    : {
-        satisfied: false,
-        summary: `no provider in ~/.pi/agent/models.json points at ${needle}`,
-        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,
-  readPiModelsJson: () => string | undefined = defaultReadPiModelsJson
+  readPiModelsJson: () => string | undefined = readPiModels
 ): Effect.Effect<string> =>
   Effect.map(registry.healthCheckAll, (statuses) => {
     const lines: Array<string> = []
@@ -186,18 +241,20 @@ export const makeDoctorProgram = (
     if (geminiRelevant || bridge !== undefined) {
       lines.push("")
       lines.push("prerequisites:")
-      if (geminiRelevant) {
-        const gemini = geminiPrerequisites(environment)
-        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) {
-        lines.push(`  ${bridge.satisfied ? "✔" : "?"} pi-gemini-bridge: ${bridge.summary}`)
-        if (bridge.hint !== undefined) {
-          lines.push(...wrap(bridge.hint, 78, "      "))
-        }
+        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 }
   })

package/src/NodeGeminiAcpBridge.ts

@@ -195,6 +195,17 @@ const toolResultInLastMessage = (
 const userTextInLastMessage = (body: JsonValue): string =>
   contentBlocksText(jsonField(lastMessage(body), "content"))
 
+/**
+ * The route to match, without the query string. `request.url` carries it,
+ * and pi's bundled Anthropic SDK posts to `/v1/messages?beta=true` for
+ * tool-enabled requests — routing on the raw value 404s exactly the request
+ * this bridge exists to serve.
+ */
+export const requestPath = (url: string | undefined): string => {
+  const path = (url ?? "/").split(/[?#]/)[0]
+  return path === undefined || path.length === 0 ? "/" : path
+}
+
 const anthropicResponse = (model: string, outcome: TurnOutcome): JsonRecord => ({
   id: `msg_${Date.now()}`,
   type: "message",
@@ -211,9 +222,15 @@ const anthropicResponse = (model: string, outcome: TurnOutcome): JsonRecord => (
   usage: { input_tokens: 0, output_tokens: 0 }
 })
 
-export const handleMessagesRequest = Effect.fn(
-  "@llm4ts/runner/NodeGeminiAcpBridge.handleMessagesRequest"
-)(function* (state: BridgeState, body: JsonValue): Effect.fn.Return<JsonRecord, LlmError> {
+/**
+ * Drive one turn to its outcome. Split from the response rendering because a
+ * streaming request must write `message_start` before this resolves — pi
+ * hardcodes `stream: true`, and gemini can take a while to answer.
+ */
+export const resolveTurn = Effect.fn("@llm4ts/runner/NodeGeminiAcpBridge.resolveTurn")(function* (
+  state: BridgeState,
+  body: JsonValue
+): Effect.fn.Return<TurnOutcome, LlmError> {
   const continuation = toolResultInLastMessage(body)
   let pendingToResolve: PendingToolCall | undefined
   if (continuation !== undefined) {
@@ -264,7 +281,123 @@ export const handleMessagesRequest = Effect.fn(
   const outcome = yield* Deferred.await(outcomeDeferred)
   yield* Ref.set(state.turnOutcome, Option.none())
 
-  return anthropicResponse(jsonStringField(body, "model") ?? "gemini", outcome)
+  return outcome
+})
+
+export const requestModel = (body: JsonValue): string => jsonStringField(body, "model") ?? "gemini"
+
+/**
+ * One Anthropic Messages streaming event. pi's bundled SDK hardcodes
+ * `stream: true` on every request and there is no compatibility flag to turn
+ * it off, so this transport — not the single-JSON one — is the live path.
+ *
+ * ACP hands this bridge a finished turn rather than a token stream, so each
+ * block is emitted as one delta. That is a well-formed event sequence the
+ * client reassembles correctly; it simply arrives in a single chunk instead
+ * of token by token.
+ */
+export interface StreamEvent {
+  readonly event: string
+  readonly data: JsonRecord
+}
+
+const emptyUsage: JsonRecord = { input_tokens: 0, output_tokens: 0 }
+
+/** Sent before the turn resolves, so the client sees a live response. */
+export const turnStartEvents = (id: string, model: string): ReadonlyArray<StreamEvent> => [
+  {
+    event: "message_start",
+    data: {
+      type: "message_start",
+      message: {
+        id,
+        type: "message",
+        role: "assistant",
+        model,
+        content: [],
+        stop_reason: null,
+        stop_sequence: null,
+        usage: emptyUsage
+      }
+    }
+  }
+]
+
+/**
+ * The blocks and stop events for a resolved turn. A `tool_use` block carries
+ * an empty `input` and supplies the real arguments through `input_json_delta`,
+ * which is the shape the Anthropic client expects to accumulate.
+ */
+export const turnOutcomeEvents = (outcome: TurnOutcome): ReadonlyArray<StreamEvent> => {
+  const blocks: ReadonlyArray<StreamEvent> =
+    outcome._tag === "Text"
+      ? [
+          {
+            event: "content_block_start",
+            data: {
+              type: "content_block_start",
+              index: 0,
+              content_block: { type: "text", text: "" }
+            }
+          },
+          {
+            event: "content_block_delta",
+            data: {
+              type: "content_block_delta",
+              index: 0,
+              delta: { type: "text_delta", text: outcome.text }
+            }
+          }
+        ]
+      : [
+          {
+            event: "content_block_start",
+            data: {
+              type: "content_block_start",
+              index: 0,
+              content_block: { type: "tool_use", id: outcome.id, name: outcome.name, input: {} }
+            }
+          },
+          {
+            event: "content_block_delta",
+            data: {
+              type: "content_block_delta",
+              index: 0,
+              delta: { type: "input_json_delta", partial_json: JSON.stringify(outcome.input) }
+            }
+          }
+        ]
+  return [
+    ...blocks,
+    { event: "content_block_stop", data: { type: "content_block_stop", index: 0 } },
+    {
+      event: "message_delta",
+      data: {
+        type: "message_delta",
+        delta: {
+          stop_reason: outcome._tag === "Text" ? "end_turn" : "tool_use",
+          stop_sequence: null
+        },
+        usage: { output_tokens: 0 }
+      }
+    },
+    { event: "message_stop", data: { type: "message_stop" } }
+  ]
+}
+
+/** A failure after `message_start` can only be reported in-band. */
+export const turnErrorEvent = (message: string): StreamEvent => ({
+  event: "error",
+  data: { type: "error", error: { type: "api_error", message } }
+})
+
+export const messageId = (): string => `msg_${Date.now()}`
+
+export const handleMessagesRequest = Effect.fn(
+  "@llm4ts/runner/NodeGeminiAcpBridge.handleMessagesRequest"
+)(function* (state: BridgeState, body: JsonValue): Effect.fn.Return<JsonRecord, LlmError> {
+  const outcome = yield* resolveTurn(state, body)
+  return anthropicResponse(requestModel(body), outcome)
 })
 
 const readBody = (request: IncomingMessage): Effect.Effect<string, ProviderError> =>
@@ -285,6 +418,47 @@ const parseJsonBody = (raw: string): Effect.Effect<JsonValue, InvalidRequestErro
     catch: () => InvalidRequestError.make({ message: "request body is not valid JSON" })
   })
 
+const writeStreamEvent = (response: ServerResponse, event: StreamEvent): void => {
+  response.write(`event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`)
+}
+
+/**
+ * Stream one turn. The head goes out before the turn resolves so the client
+ * has a live response while gemini works; after that point a failure can only
+ * be reported as an in-band `error` event, never as a status code.
+ */
+const respondStreaming = (
+  response: ServerResponse,
+  state: BridgeState,
+  body: JsonValue
+): Effect.Effect<void> =>
+  Effect.sync(() => {
+    response.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    })
+    for (const event of turnStartEvents(messageId(), requestModel(body))) {
+      writeStreamEvent(response, event)
+    }
+  }).pipe(
+    Effect.andThen(resolveTurn(state, body)),
+    Effect.matchEffect({
+      onSuccess: (outcome) =>
+        Effect.sync(() => {
+          for (const event of turnOutcomeEvents(outcome)) {
+            writeStreamEvent(response, event)
+          }
+          response.end()
+        }),
+      onFailure: (error) =>
+        Effect.sync(() => {
+          writeStreamEvent(response, turnErrorEvent(error.message))
+          response.end()
+        })
+    })
+  )
+
 const writeJson = (response: ServerResponse, status: number, body: JsonValue): void => {
   const text = JSON.stringify(body)
   response.writeHead(status, { "Content-Type": "application/json" })
@@ -356,7 +530,7 @@ export const runGeminiAcpBridge = Effect.fn("@llm4ts/runner/NodeGeminiAcpBridge.
   const state = yield* makeBridgeState(session, config.cwd, mcpServerUrl, forkBackground)
 
   const requestListener = (request: IncomingMessage, response: ServerResponse): void => {
-    const path = request.url ?? "/"
+    const path = requestPath(request.url)
     if (request.method !== "POST" || (path !== "/v1/messages" && path !== "/mcp")) {
       writeJson(response, 404, { error: { message: "not found" } })
       return
@@ -369,23 +543,30 @@ export const runGeminiAcpBridge = Effect.fn("@llm4ts/runner/NodeGeminiAcpBridge.
         const tools = yield* Ref.get(state.tools)
         const mcpTools = tools.map((tool) => anthropicToolToMcpTool(state, tool))
         const reply = yield* handleMcpRequest(body, mcpTools)
-        return { status: 200, body: reply ?? {} }
+        return yield* Effect.sync(() => writeJson(response, 200, reply ?? {}))
+      }
+      if (jsonBooleanField(body, "stream") === true) {
+        return yield* respondStreaming(response, state, body)
       }
       const reply = yield* handleMessagesRequest(state, body)
-      return { status: 200, body: reply }
+      return yield* Effect.sync(() => writeJson(response, 200, reply))
     }).pipe(
+      // Only a failure before the head went out can still choose a status;
+      // `respondStreaming` owns everything after that and never fails.
       Effect.catch((error) =>
-        Effect.succeed({
-          status: errorStatus(error),
-          body: { error: { message: error.message } }
+        Effect.sync(() => {
+          if (!response.headersSent) {
+            writeJson(response, errorStatus(error), { error: { message: error.message } })
+          }
         })
       )
     )
 
-    Effect.runPromise(handled).then(
-      ({ status, body }: { status: number; body: JsonValue }) => writeJson(response, status, body),
-      (defect: unknown) => writeJson(response, 500, { error: { message: String(defect) } })
-    )
+    Effect.runPromise(handled).catch((defect: unknown) => {
+      if (!response.headersSent) {
+        writeJson(response, 500, { error: { message: String(defect) } })
+      }
+    })
   }
 
   const server = yield* acquireServer(config.port, requestListener)