@llm4ts/runner 2.41.0 → 2.43.0

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,38 @@ 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
+    }).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
@@ -749,6 +779,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
       capacity: roster.capacity,
       capacityChanged: roster.capacityChanged,
       executor: held.executor,
+      clone: held.clone,
       contractOf: (id) => roster.executors.find((spec) => spec.id === id)?.contract,
       history: held.history
     })
@@ -820,6 +851,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
                       events: laneEvents,
                       eager: true,
                       label,
+                      ...(contextOptions?.ifFree === true ? { ifFree: true } : {}),
                       ...(contextOptions?.prefer === undefined
                         ? {}
                         : { prefer: contextOptions.prefer })

package/src/NodeGeminiAcpBridge.ts

@@ -400,10 +400,23 @@ export const handleMessagesRequest = Effect.fn(
   return anthropicResponse(requestModel(body), outcome)
 })
 
-const readBody = (request: IncomingMessage): Effect.Effect<string, ProviderError> =>
+/** 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 +425,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 +473,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 +505,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> =>

package/src/NodeGeminiModelBridge.ts

@@ -0,0 +1,350 @@
+import { existsSync, readdirSync } from "node:fs"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { InvalidRequestError, ProviderError, type LlmError } from "@llm4ts/core/Errors"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import type { TemporaryFilesShape } from "@llm4ts/core/TemporaryFiles"
+import type { JsonValue } from "@llm4ts/core/providers/CliSupport"
+import { parseGeminiCliStreamEvent } from "@llm4ts/core/providers/GeminiCliProvider"
+import {
+  chatRequestFrom,
+  completionChunks,
+  completionJson,
+  correctionTranscript,
+  denyAllToolsPolicyToml,
+  modelModeSettingsJson,
+  openAiUsage,
+  parseModelReply,
+  systemFileFor,
+  transcriptFor,
+  type GeminiTokens,
+  type ModelReply,
+  type OpenAiUsage
+} from "@llm4ts/core/providers/GeminiModelBridge"
+import {
+  acquireServer,
+  errorStatus,
+  parseJsonBody,
+  readBody,
+  requestPath,
+  writeJson
+} from "./NodeGeminiAcpBridge.ts"
+
+/**
+ * The bridge's model route (ADR 0037): `/v1/chat/completions` in OpenAI's
+ * shape, for pi's `"api": "openai-completions"` custom provider. Each
+ * request is one `gemini` call with Gemini CLI's own agent switched off —
+ * pi's system prompt in place of Gemini's (`GEMINI_SYSTEM_MD`), every tool
+ * denied by an admin policy, sub-agents off in the system settings — so
+ * Gemini answers as a plain model and pi runs its own tools. Only Gemini
+ * CLI talks to Google, under its own login; this module never reads or
+ * forwards a credential.
+ */
+
+export interface GeminiModelCallConfig {
+  readonly executor: ProcessExecutorShape
+  readonly temporaryFiles: TemporaryFilesShape
+  /** Where `gemini` runs: an empty directory, so no project GEMINI.md is read. */
+  readonly cwd: string
+  /** The Gemini model, overriding the one pi's request names (`LLM4TS_GEMINI_MODEL`). */
+  readonly model?: string
+  readonly envVars?: Readonly<Record<string, string>>
+}
+
+export interface GeminiModelBridgeConfig extends GeminiModelCallConfig {
+  readonly port: number
+  /**
+   * `.toml` files in Gemini CLI's standard system policy directory: with
+   * any, the CLI ignores `--admin-policy`, so the tools would stay in view.
+   * Default: what is on this machine (`systemAdminPolicies`).
+   */
+  readonly systemPolicies?: ReadonlyArray<string>
+}
+
+export interface RunningGeminiModelBridge {
+  readonly port: number
+  readonly baseUrl: string
+}
+
+/** The standard directories Gemini CLI reads system (admin) policies from. */
+export const systemPolicyDirectories: ReadonlyArray<string> = [
+  "/etc/gemini-cli/policies",
+  "/Library/Application Support/GeminiCli/policies",
+  "C:\\ProgramData\\gemini-cli\\policies"
+]
+
+/** The admin policy files on this machine that would make Gemini CLI ignore `--admin-policy`. */
+export const systemAdminPolicies = (): ReadonlyArray<string> =>
+  systemPolicyDirectories.flatMap((directory) => {
+    try {
+      return existsSync(directory)
+        ? readdirSync(directory)
+            .filter((file) => file.endsWith(".toml"))
+            .map((file) => join(directory, file))
+        : []
+    } catch {
+      return []
+    }
+  })
+
+export const systemPolicyProblem = (policies: ReadonlyArray<string>): string =>
+  [
+    `Gemini CLI has system admin policies (${policies.join(", ")}), so it ignores the`,
+    "--admin-policy the model bridge relies on to take every tool out of the model's view.",
+    "The bridge will not run Gemini with its tools still in reach (ADR 0037); use",
+    "LLM4TS_GEMINI_BRIDGE_MODE=acp, or ask the administrator to allow this policy."
+  ].join(" ")
+
+interface GeminiTurn {
+  readonly text: string
+  readonly tokens: GeminiTokens | undefined
+}
+
+/** One `gemini` call over `transcript`, its system file and lock-down written for the call. */
+const geminiTurn = (
+  config: GeminiModelCallConfig,
+  model: string,
+  system: string,
+  transcript: string
+): Effect.Effect<GeminiTurn, LlmError> =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const systemFile = yield* config.temporaryFiles.write("gemini-system-", ".md", system)
+      const settings = yield* config.temporaryFiles.write(
+        "gemini-settings-",
+        ".json",
+        modelModeSettingsJson
+      )
+      const policy = yield* config.temporaryFiles.write(
+        "gemini-deny-all-",
+        ".toml",
+        denyAllToolsPolicyToml
+      )
+      const events = yield* Stream.runCollect(
+        config.executor
+          .runStreamingWithStdin(
+            [
+              "gemini",
+              // Bound to its flag, so it can never read as a flag of its own.
+              `--model=${model}`,
+              "--output-format",
+              "stream-json",
+              "-e",
+              "none",
+              "--admin-policy",
+              policy
+            ],
+            config.cwd,
+            {
+              ...config.envVars,
+              GEMINI_CLI_TRUST_WORKSPACE: "true",
+              GEMINI_SYSTEM_MD: systemFile,
+              GEMINI_CLI_SYSTEM_SETTINGS_PATH: settings
+            },
+            transcript
+          )
+          .pipe(Stream.map(parseGeminiCliStreamEvent))
+      )
+      let text = ""
+      let tokens: GeminiTokens | undefined
+      for (const event of events) {
+        switch (event._tag) {
+          case "Message":
+            if (event.role === "assistant" && event.content !== undefined) {
+              text += event.content
+            }
+            break
+          case "Error":
+            return yield* ProviderError.make({
+              message: `gemini: ${event.message ?? "error"}`
+            })
+          case "Result":
+            if (event.status === "error") {
+              return yield* ProviderError.make({
+                message: `gemini: ${event.errorMessage ?? "the call failed"}`
+              })
+            }
+            tokens =
+              event.stats === undefined
+                ? undefined
+                : {
+                    ...(event.stats.inputTokens === undefined
+                      ? {}
+                      : { inputTokens: event.stats.inputTokens }),
+                    ...(event.stats.outputTokens === undefined
+                      ? {}
+                      : { outputTokens: event.stats.outputTokens }),
+                    ...(event.stats.cached === undefined ? {} : { cached: event.stats.cached })
+                  }
+            break
+          default:
+            break
+        }
+      }
+      return { text, tokens }
+    })
+  )
+
+const addTokens = (
+  left: GeminiTokens | undefined,
+  right: GeminiTokens | undefined
+): GeminiTokens => ({
+  inputTokens: (left?.inputTokens ?? 0) + (right?.inputTokens ?? 0),
+  outputTokens: (left?.outputTokens ?? 0) + (right?.outputTokens ?? 0),
+  cached: (left?.cached ?? 0) + (right?.cached ?? 0)
+})
+
+/** The largest request the bridge reads: a long conversation, not an unbounded upload. */
+const maxRequestBytes = 32 * 1024 * 1024
+
+/** What a Gemini model id looks like: `gemini-3.8-flash`, `gemini-2.5-pro-001`. */
+const modelName = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u
+
+export interface ChatCompletionOutcome {
+  readonly model: string
+  readonly reply: ModelReply
+  readonly usage: OpenAiUsage
+}
+
+/**
+ * One chat completion: a `gemini` call, and a second one only when the
+ * first reply holds a tool call that cannot be used — the model then sees
+ * its reply and why. A second bad reply goes back to pi as text.
+ */
+export const handleChatCompletion = Effect.fn("@llm4ts/runner/NodeGeminiModelBridge.handle")(
+  function* (
+    config: GeminiModelCallConfig,
+    body: JsonValue
+  ): Effect.fn.Return<ChatCompletionOutcome, LlmError | InvalidRequestError> {
+    const request = chatRequestFrom(body)
+    if (request._tag === "Invalid") {
+      return yield* InvalidRequestError.make({ message: request.reason })
+    }
+    const model = config.model ?? request.model
+    // The model reaches Gemini CLI's arguments: a name only, never a flag.
+    if (!modelName.test(model)) {
+      return yield* InvalidRequestError.make({
+        message: `"${model}" is not a model name (letters, digits, . _ : -, starting with a letter or digit)`
+      })
+    }
+    const system = systemFileFor(request)
+    const transcript = transcriptFor(request.messages)
+    const toolNames = request.tools.map((tool) => tool.name)
+    const first = yield* geminiTurn(config, model, system, transcript)
+    const reply = parseModelReply(first.text, toolNames)
+    if (reply._tag !== "Malformed") {
+      return { model, reply, usage: openAiUsage(first.tokens) }
+    }
+    const second = yield* geminiTurn(
+      config,
+      model,
+      system,
+      correctionTranscript(transcript, first.text, reply.error)
+    )
+    return {
+      model,
+      reply: parseModelReply(second.text, toolNames),
+      usage: openAiUsage(addTokens(first.tokens, second.tokens))
+    }
+  }
+)
+
+let completions = 0
+const nextIds = (): { readonly id: string; readonly callId: string } => {
+  completions += 1
+  return { id: `chatcmpl-llm4ts-${completions}`, callId: `call_llm4ts_${completions}` }
+}
+
+const writeChunks = (response: ServerResponse, chunks: ReadonlyArray<JsonValue>): void => {
+  response.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive"
+  })
+  for (const chunk of chunks) {
+    response.write(`data: ${JSON.stringify(chunk)}\n\n`)
+  }
+  response.write("data: [DONE]\n\n")
+  response.end()
+}
+
+const streamWanted = (body: JsonValue): boolean => {
+  const request = chatRequestFrom(body)
+  return request._tag === "Request" && request.stream
+}
+
+export const runGeminiModelBridge = Effect.fn("@llm4ts/runner/NodeGeminiModelBridge.run")(
+  function* (
+    config: GeminiModelBridgeConfig
+  ): Effect.fn.Return<RunningGeminiModelBridge, LlmError, Scope.Scope> {
+    const policies = config.systemPolicies ?? systemAdminPolicies()
+    if (policies.length > 0) {
+      return yield* ProviderError.make({ message: systemPolicyProblem(policies) })
+    }
+
+    const listener = (request: IncomingMessage, response: ServerResponse): void => {
+      if (request.method !== "POST" || requestPath(request.url) !== "/v1/chat/completions") {
+        writeJson(response, 404, { error: { message: "not found" } })
+        return
+      }
+      // pi posts JSON from Node, with no Origin. A browser page posting to
+      // this loopback port (a cross-site form needs no preflight as
+      // text/plain) is refused before anything runs.
+      const contentType = request.headers["content-type"] ?? ""
+      // A DNS name rebound to 127.0.0.1 still sends its own Host.
+      const host = (request.headers.host ?? "").replace(/:\d+$/u, "")
+      if (
+        request.headers.origin !== undefined ||
+        !contentType.includes("application/json") ||
+        !["127.0.0.1", "localhost", "[::1]"].includes(host)
+      ) {
+        writeJson(response, 403, {
+          error: { message: "the bridge answers JSON requests from local tools only" }
+        })
+        return
+      }
+      const handled = Effect.gen(function* () {
+        const body = yield* parseJsonBody(yield* readBody(request, maxRequestBytes))
+        const outcome = yield* handleChatCompletion(config, body)
+        const { id, callId } = nextIds()
+        const created = Math.floor(Date.now() / 1000)
+        if (streamWanted(body)) {
+          return yield* Effect.sync(() =>
+            writeChunks(
+              response,
+              completionChunks(id, outcome.model, outcome.reply, outcome.usage, created, callId)
+            )
+          )
+        }
+        return yield* Effect.sync(() =>
+          writeJson(
+            response,
+            200,
+            completionJson(id, outcome.model, outcome.reply, outcome.usage, created, callId)
+          )
+        )
+      }).pipe(
+        Effect.catch((error) =>
+          Effect.sync(() => {
+            if (!response.headersSent) {
+              writeJson(response, errorStatus(error), { error: { message: error.message } })
+            }
+          })
+        )
+      )
+      Effect.runPromise(handled).catch((defect: unknown) => {
+        if (!response.headersSent) {
+          writeJson(response, 500, { error: { message: String(defect) } })
+        }
+      })
+    }
+
+    const server = yield* acquireServer(config.port, listener)
+    const address = server.address()
+    const port = address !== null && typeof address !== "string" ? address.port : config.port
+    return { port, baseUrl: `http://127.0.0.1:${port}` }
+  }
+)

package/src/PiModels.ts

@@ -34,6 +34,26 @@ export const geminiBridgePort = (
     ? environment.LLM4TS_GEMINI_BRIDGE_PORT.trim()
     : defaultGeminiBridgePort
 
+/**
+ * Which route the bridge serves (ADR 0037): `acp` (ADR 0016's Anthropic
+ * Messages over a Gemini ACP session, the default) or `model` (OpenAI chat
+ * completions over one locked-down `gemini` call per request).
+ */
+export type GeminiBridgeMode =
+  | { readonly _tag: "Mode"; readonly mode: "acp" | "model" }
+  | { readonly _tag: "Unknown"; readonly value: string }
+
+export const geminiBridgeMode = (
+  environment: Readonly<Record<string, string | undefined>>
+): GeminiBridgeMode => {
+  const value = (environment.LLM4TS_GEMINI_BRIDGE_MODE ?? "").trim().toLowerCase()
+  return value === "" || value === "acp"
+    ? { _tag: "Mode", mode: "acp" }
+    : value === "model"
+      ? { _tag: "Mode", mode: "model" }
+      : { _tag: "Unknown", value }
+}
+
 /**
  * One value pi accepts for `--model`: `<provider>/<model>`, where the
  * provider is a key under `providers` in `~/.pi/agent/models.json` and the