@llm4ts/runner 2.42.0 → 2.44.0

package/src/Doctor.ts

@@ -9,8 +9,10 @@ import { nodeProcessExecutor } from "./NodeProcessExecutor.ts"
 import {
   defaultReadPiModelsJson as readPiModels,
   geminiBridgePort as bridgePort,
-  piModelsConfig as parsePiModels
+  piModelsConfig as parsePiModels,
+  geminiBridgeMode
 } from "./PiModels.ts"
+import { systemAdminPolicies, systemPolicyProblem } from "./NodeGeminiModelBridge.ts"
 import { otelConfig, otelDoctorLine, probeOtelEndpoint, type OtelConfig } from "./Otel.ts"
 
 const credentialKeys = [
@@ -210,6 +212,50 @@ export const geminiBridgePrerequisites = (
   }
 }
 
+/** Gemini CLI's own words on third-party access (0.62.0, `docs/resources/tos-privacy.md`). */
+export const geminiTermsClause =
+  "Directly accessing the services powering Gemini CLI (for example, the Gemini Code Assist " +
+  "service) using third-party software, tools, or services (for example, using OpenClaw with " +
+  "Gemini CLI OAuth) is a violation of applicable terms and policies. Such actions may be " +
+  "grounds for suspension or termination of your account."
+
+/**
+ * The model mode of the bridge (ADR 0037): whether a system admin policy
+ * would keep Gemini's tools in view, how pi's provider must be shaped, and
+ * the terms clause the customer confirms against. `undefined` unless the
+ * bridge runs in model mode.
+ */
+export const geminiModelModePrerequisites = (
+  environment: Readonly<Record<string, string | undefined>>,
+  systemPolicies: ReadonlyArray<string>
+): PrerequisiteReport | undefined => {
+  const mode = geminiBridgeMode(environment)
+  if (!truthy(environment.LLM4TS_GEMINI_BRIDGE) || mode._tag !== "Mode" || mode.mode !== "model") {
+    return undefined
+  }
+  const detail = [
+    'pi\'s bridge provider in ~/.pi/agent/models.json needs "api": "openai-completions"',
+    "(the route is /v1/chat/completions); only Gemini CLI talks to Google, under its own",
+    "login, and llm4ts never reads or forwards its credentials. Gemini CLI's terms say:",
+    `  "${geminiTermsClause}"`,
+    "Using Gemini CLI as a model for pi stays close to that clause: confirm with Google",
+    "before relying on it."
+  ]
+  return systemPolicies.length > 0
+    ? {
+        satisfied: false,
+        summary: `system admin policies make Gemini CLI ignore the bridge's: ${systemPolicies.join(", ")}`,
+        hint: systemPolicyProblem(systemPolicies),
+        detail
+      }
+    : {
+        satisfied: true,
+        summary:
+          "model mode: Gemini CLI answers as a plain model, its prompt replaced and every tool denied",
+        detail
+      }
+}
+
 export const makeDoctorProgram = (
   registry: ConnectorRegistryShape = nodeFlowRunnerDependencies().registry,
   environment: Readonly<Record<string, string | undefined>> = process.env,
@@ -223,7 +269,9 @@ export const makeDoctorProgram = (
     environment
   ),
   /** Whether the OTLP endpoint answers (ADR 0026); the network probe by default. */
-  probeOtel: (config: OtelConfig) => Effect.Effect<boolean | undefined> = probeOtelEndpoint
+  probeOtel: (config: OtelConfig) => Effect.Effect<boolean | undefined> = probeOtelEndpoint,
+  /** Gemini CLI's system admin policy files (ADR 0037); this machine's by default. */
+  systemPolicies: () => ReadonlyArray<string> = systemAdminPolicies
 ): Effect.Effect<string> => {
   const otel = otelConfig(environment)
   return Effect.map(
@@ -266,6 +314,7 @@ export const makeDoctorProgram = (
             id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value
         )
       const bridge = geminiBridgePrerequisites(environment, readPiModelsJson())
+      const modelMode = geminiModelModePrerequisites(environment, systemPolicies())
       if (geminiRelevant || bridge !== undefined) {
         lines.push("")
         lines.push("prerequisites:")
@@ -284,6 +333,9 @@ export const makeDoctorProgram = (
         if (bridge !== undefined) {
           pushReport("pi-gemini-bridge", bridge)
         }
+        if (modelMode !== undefined) {
+          pushReport("pi-gemini-bridge model mode", modelMode)
+        }
       }
 
       lines.push("")

package/src/FlowRunner.ts

@@ -1,3 +1,5 @@
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
 import { join } from "node:path"
 import * as Cause from "effect/Cause"
 import * as Clock from "effect/Clock"
@@ -25,11 +27,13 @@ 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 { runGeminiModelBridge } from "./NodeGeminiModelBridge.ts"
 import {
   bridgeModelProblem,
   defaultReadPiModelsJson,
   geminiBridgePort,
-  resolveBridgeModel
+  resolveBridgeModel,
+  geminiBridgeMode
 } from "./PiModels.ts"
 import {
   appendCostRecord,
@@ -128,6 +132,8 @@ export interface FlowRunnerDependencies {
   readonly files: PlainFileStoreShape
   /** pi's own model config (ADR 0016), injectable so a test never reads $HOME. */
   readonly readPiModelsJson?: () => string | undefined
+  /** Files the Gemini model bridge writes per call (ADR 0037); temporary files on disk by default. */
+  readonly temporaryFiles?: TemporaryFilesShape
   /** For the hosted TypeSafe judgment backend; defaults to the Node client. */
   readonly http?: HttpClientShape
   /** Where `--transcript` writes, given its directory; files on disk by default. */
@@ -280,14 +286,42 @@ const geminiBridgeSeats = Effect.fn("@llm4ts/runner/FlowRunner.geminiBridgeSeats
   }
   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))
+  const mode = geminiBridgeMode(environment)
+  if (mode._tag === "Unknown") {
+    return yield* FlowLlmError.from(
+      ProviderError.make({
+        message: `LLM4TS_GEMINI_BRIDGE_MODE is "${mode.value}"; use acp (the default) or model`
+      })
+    )
+  }
+  const geminiModel =
+    environment.LLM4TS_GEMINI_MODEL === undefined ? {} : { model: environment.LLM4TS_GEMINI_MODEL }
+  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.
+    const scratch = yield* Effect.acquireRelease(
+      Effect.sync(() => mkdtempSync(join(tmpdir(), "llm4ts-gemini-model-"))),
+      (directory) => Effect.sync(() => rmSync(directory, { recursive: true, force: true }))
+    )
+    yield* runGeminiModelBridge({
+      port: Number(port),
+      cwd: scratch,
+      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 })
+    }).pipe(Effect.mapError(FlowLlmError.from))
+  } else {
+    yield* runGeminiAcpBridge({
+      port: Number(port),
+      cwd: options.workDir,
+      executor: dependencies.process,
+      ...geminiModel
+    }).pipe(Effect.mapError(FlowLlmError.from))
+  }
 
   return (config: ConnectorConfig): ConnectorConfig =>
     isPiSeat(config) && config.model === undefined

package/src/GeminiBridgeServe.ts

@@ -0,0 +1,128 @@
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import type { LlmError } from "@llm4ts/core/Errors"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import type { TemporaryFilesShape } from "@llm4ts/core/TemporaryFiles"
+import { runGeminiAcpBridge } from "./NodeGeminiAcpBridge.ts"
+import { runGeminiModelBridge, systemAdminPolicies } from "./NodeGeminiModelBridge.ts"
+
+/**
+ * `llm4ts gemini-bridge`: the Gemini bridge on its own, outside any flow
+ * run, so `pi` (or any OpenAI-compatible client) can use the Gemini CLI
+ * subscription directly. ADR 0016 deferred this entry point; ADR 0037's
+ * model mode makes it an OpenAI-compatible server like LM Studio's. The
+ * bridge's code is the flow runner's; only the caller changes.
+ */
+
+export interface GeminiBridgeOptions {
+  readonly port: number
+  /** `model` (OpenAI chat completions, ADR 0037) or `acp` (Anthropic Messages, ADR 0016). */
+  readonly mode: "model" | "acp"
+  /** The Gemini model every request runs on, whatever the client names. */
+  readonly model?: string
+  /** A token requests must carry (model mode), printed as pi's `apiKey`. */
+  readonly token?: string
+}
+
+export interface GeminiBridgeDependencies {
+  readonly executor: ProcessExecutorShape
+  readonly temporaryFiles: TemporaryFilesShape
+  /** Gemini CLI's system admin policy files; this machine's by default. */
+  readonly systemPolicies?: ReadonlyArray<string>
+  readonly log: (line: string) => Effect.Effect<void>
+  /** Runs while the bridge serves; the bridge stops when it ends (Ctrl-C in the CLI). */
+  readonly until: (baseUrl: string) => Effect.Effect<void>
+}
+
+/** The model id the printed pi config names when `--model` names none. */
+export const defaultBridgeModelId = "gemini-3.8-flash"
+
+/** pi's provider entry for `~/.pi/agent/models.json`, for this mode and port. */
+export const piProviderSnippet = (
+  mode: "model" | "acp",
+  port: number,
+  model: string,
+  token?: string
+): string =>
+  JSON.stringify(
+    {
+      providers: {
+        "gemini-bridge": {
+          baseUrl: mode === "model" ? `http://127.0.0.1:${port}/v1` : `http://127.0.0.1:${port}`,
+          api: mode === "model" ? "openai-completions" : "anthropic-messages",
+          apiKey: token ?? "bridge-unused",
+          models: [{ id: model }]
+        }
+      }
+    },
+    null,
+    2
+  )
+
+export const makeGeminiBridgeProgram = (
+  options: GeminiBridgeOptions,
+  dependencies: GeminiBridgeDependencies
+): Effect.Effect<void, LlmError> =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const model = options.model === undefined ? {} : { model: options.model }
+      const running =
+        options.mode === "model"
+          ? yield* Effect.flatMap(
+              // An empty directory, so no project GEMINI.md reaches the model.
+              Effect.acquireRelease(
+                Effect.sync(() => mkdtempSync(join(tmpdir(), "llm4ts-gemini-model-"))),
+                (directory) =>
+                  Effect.sync(() => rmSync(directory, { recursive: true, force: true }))
+              ),
+              (scratch) =>
+                runGeminiModelBridge({
+                  port: options.port,
+                  cwd: scratch,
+                  executor: dependencies.executor,
+                  temporaryFiles: dependencies.temporaryFiles,
+                  systemPolicies: dependencies.systemPolicies ?? systemAdminPolicies(),
+                  ...model,
+                  ...(options.token === undefined ? {} : { token: options.token })
+                })
+            )
+          : yield* runGeminiAcpBridge({
+              port: options.port,
+              cwd: process.cwd(),
+              executor: dependencies.executor,
+              ...model
+            })
+      const id = options.model ?? defaultBridgeModelId
+      const url = options.mode === "model" ? `${running.baseUrl}/v1` : running.baseUrl
+      yield* Effect.forEach(
+        [
+          `gemini bridge (${options.mode === "model" ? "model mode: OpenAI chat completions" : "ACP mode: Anthropic Messages"}) listening on ${url}`,
+          "",
+          "pi provider for ~/.pi/agent/models.json:",
+          piProviderSnippet(
+            options.mode,
+            running.port,
+            id,
+            options.mode === "model" ? options.token : undefined
+          ),
+          "",
+          `then: pi --model gemini-bridge/${id}`,
+          ...(options.mode === "model"
+            ? [
+                "",
+                "Only Gemini CLI talks to Google, under its own login. Its terms forbid direct",
+                "third-party access to its services; confirm with Google before relying on this",
+                "(`LLM4TS_GEMINI_BRIDGE=1 LLM4TS_GEMINI_BRIDGE_MODE=model llm4ts doctor` quotes them)."
+              ]
+            : []),
+          "",
+          "Ctrl-C stops it."
+        ],
+        dependencies.log,
+        { discard: true }
+      )
+      yield* dependencies.until(running.baseUrl)
+    })
+  )

package/src/NodeGeminiAcpBridge.ts

@@ -1,4 +1,11 @@
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { timingSafeEqual } from "node:crypto"
+import {
+  createServer,
+  type IncomingHttpHeaders,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse
+} from "node:http"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
@@ -400,10 +407,59 @@ export const handleMessagesRequest = Effect.fn(
   return anthropicResponse(requestModel(body), outcome)
 })
 
-const readBody = (request: IncomingMessage): Effect.Effect<string, ProviderError> =>
+/**
+ * Why a request may not reach the bridge, or nothing when it may: both
+ * routes answer local tools only. pi and gemini post JSON from Node, with
+ * no Origin; a browser page posting to this loopback port (a cross-site
+ * form needs no preflight as text/plain) carries one, and a DNS name
+ * rebound to 127.0.0.1 still sends its own Host. With a token, the request
+ * must carry it as a bearer (pi sends its `apiKey` that way).
+ */
+export const localRequestProblem = (
+  headers: IncomingHttpHeaders,
+  token?: string
+): string | undefined => {
+  const contentType = headers["content-type"] ?? ""
+  const host = (headers.host ?? "").replace(/:\d+$/u, "")
+  if (headers.origin !== undefined) {
+    return "the bridge answers local tools, not browser pages"
+  }
+  if (!contentType.includes("application/json")) {
+    return "the bridge answers JSON requests only"
+  }
+  if (!["127.0.0.1", "localhost", "[::1]"].includes(host)) {
+    return "the bridge answers requests to 127.0.0.1 only"
+  }
+  if (token !== undefined) {
+    const given = Buffer.from(headers.authorization ?? "")
+    const wanted = Buffer.from(`Bearer ${token}`)
+    if (given.length !== wanted.length || !timingSafeEqual(given, wanted)) {
+      return "the bridge's token is missing or wrong"
+    }
+  }
+  return undefined
+}
+
+/** The largest request either route reads: a long conversation, not an unbounded upload. */
+export const maxRequestBytes = 32 * 1024 * 1024
+
+/** Shared with the model route (`NodeGeminiModelBridge.ts`, ADR 0037). */
+export const readBody = (
+  request: IncomingMessage,
+  maxBytes: number = Number.POSITIVE_INFINITY
+): Effect.Effect<string, ProviderError> =>
   Effect.callback((resume) => {
     const chunks: Array<Buffer> = []
-    request.on("data", (chunk: Buffer) => chunks.push(chunk))
+    let size = 0
+    request.on("data", (chunk: Buffer) => {
+      size += chunk.length
+      if (size > maxBytes) {
+        request.destroy()
+        resume(Effect.fail(ProviderError.make({ message: `request body over ${maxBytes} bytes` })))
+        return
+      }
+      chunks.push(chunk)
+    })
     request.on("end", () => resume(Effect.succeed(Buffer.concat(chunks).toString("utf8"))))
     request.on("error", (error) =>
       resume(ProviderError.make({ message: "failed to read request body", cause: error }))
@@ -412,7 +468,8 @@ const readBody = (request: IncomingMessage): Effect.Effect<string, ProviderError
 
 const parseJson = (raw: string): JsonValue => JSON.parse(raw)
 
-const parseJsonBody = (raw: string): Effect.Effect<JsonValue, InvalidRequestError> =>
+/** Shared with the model route (`NodeGeminiModelBridge.ts`, ADR 0037). */
+export const parseJsonBody = (raw: string): Effect.Effect<JsonValue, InvalidRequestError> =>
   Effect.try({
     try: () => parseJson(raw),
     catch: () => InvalidRequestError.make({ message: "request body is not valid JSON" })
@@ -459,13 +516,15 @@ const respondStreaming = (
     })
   )
 
-const writeJson = (response: ServerResponse, status: number, body: JsonValue): void => {
+/** Shared with the model route (`NodeGeminiModelBridge.ts`, ADR 0037). */
+export const writeJson = (response: ServerResponse, status: number, body: JsonValue): void => {
   const text = JSON.stringify(body)
   response.writeHead(status, { "Content-Type": "application/json" })
   response.end(text)
 }
 
-const errorStatus = (error: LlmError | InvalidRequestError): number =>
+/** Shared with the model route (`NodeGeminiModelBridge.ts`, ADR 0037). */
+export const errorStatus = (error: LlmError | InvalidRequestError): number =>
   error._tag === "InvalidRequestError" ? 400 : error._tag === "AuthenticationError" ? 401 : 502
 
 export interface GeminiAcpBridgeConfig {
@@ -489,7 +548,8 @@ const bindError = (port: number, cause: unknown): ProviderError =>
     cause
   })
 
-const acquireServer = (
+/** Shared with the model route (`NodeGeminiModelBridge.ts`, ADR 0037). */
+export const acquireServer = (
   port: number,
   listener: (request: IncomingMessage, response: ServerResponse) => void
 ): Effect.Effect<Server, ProviderError, Scope.Scope> =>
@@ -535,9 +595,14 @@ export const runGeminiAcpBridge = Effect.fn("@llm4ts/runner/NodeGeminiAcpBridge.
       writeJson(response, 404, { error: { message: "not found" } })
       return
     }
+    const problem = localRequestProblem(request.headers)
+    if (problem !== undefined) {
+      writeJson(response, 403, { error: { message: problem } })
+      return
+    }
 
     const handled = Effect.gen(function* () {
-      const raw = yield* readBody(request)
+      const raw = yield* readBody(request, maxRequestBytes)
       const body = yield* parseJsonBody(raw)
       if (path === "/mcp") {
         const tools = yield* Ref.get(state.tools)