@llm4ts/runner 0.1.0

package/src/NodeGeminiCliExecutor.ts

@@ -0,0 +1,56 @@
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import { ProviderError } from "@llm4ts/core/Errors"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import {
+  GeminiCliExecutor,
+  buildGeminiArgs,
+  extractGeminiCliResponse,
+  geminiProcessEnv,
+  parseGeminiCliStreamEvent,
+  validateGeminiExitCode,
+  type GeminiCliExecutorShape
+} from "@llm4ts/core/providers/GeminiCliProvider"
+import { nodeProcessExecutor } from "./NodeProcessExecutor.ts"
+
+const failure = (message: string): ProviderError => ProviderError.make({ message })
+
+export const makeNodeGeminiCliExecutor = (
+  executor: ProcessExecutorShape
+): GeminiCliExecutorShape => ({
+  checkGeminiInstalled: executor
+    .run(["gemini", "--version"], process.cwd(), {})
+    .pipe(
+      Effect.flatMap((result) =>
+        result.exitCode === 0
+          ? Effect.void
+          : Effect.fail(failure(`Gemini CLI is unavailable: ${result.stderr.join("\n")}`))
+      )
+    ),
+  runGeminiProcess: (prompt, config, context) =>
+    Effect.gen(function* () {
+      const result = yield* executor.runWithStdin(
+        ["gemini", ...buildGeminiArgs(config, context, "json")],
+        context.cwd ?? process.cwd(),
+        geminiProcessEnv(context),
+        prompt
+      )
+      yield* validateGeminiExitCode(result.exitCode, result.stderr.join("\n"), context.turnLimit)
+      const extracted = extractGeminiCliResponse(result.stdout.join("\n"))
+      return extracted.ok ? extracted.value : yield* failure(extracted.error)
+    }),
+  runGeminiProcessStream: (prompt, config, context) =>
+    executor
+      .runStreamingWithStdin(
+        ["gemini", ...buildGeminiArgs(config, context, "stream-json")],
+        context.cwd ?? process.cwd(),
+        geminiProcessEnv(context),
+        prompt
+      )
+      .pipe(Stream.map(parseGeminiCliStreamEvent))
+})
+
+export const nodeGeminiCliExecutor = makeNodeGeminiCliExecutor(nodeProcessExecutor)
+
+export const NodeGeminiCliExecutorLive = Layer.succeed(GeminiCliExecutor, nodeGeminiCliExecutor)

package/src/NodeHttpClient.ts

@@ -0,0 +1,224 @@
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import { HttpClient, makeHttpClient, type HttpClientShape } from "@llm4ts/core/HttpClient"
+import {
+  AuthenticationError,
+  InvalidRequestError,
+  ParseError,
+  ProviderError,
+  RateLimitError,
+  TimeoutError,
+  type LlmError
+} from "@llm4ts/core/Errors"
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+const checkedUrl = (raw: string): Effect.Effect<string, InvalidRequestError> =>
+  Effect.try({
+    try: () => new URL(raw).toString(),
+    catch: (error) =>
+      InvalidRequestError.make({
+        message: `Invalid URL '${raw}': ${errorMessage(error)}`
+      })
+  })
+
+const fetchResponse = (
+  rawUrl: string,
+  init: RequestInit,
+  timeout: Duration.Duration
+): Effect.Effect<Response, LlmError> =>
+  Effect.flatMap(checkedUrl(rawUrl), (url) =>
+    Effect.tryPromise({
+      try: (signal) =>
+        fetch(url, {
+          ...init,
+          signal
+        }),
+      catch: (error) =>
+        ProviderError.make({
+          message: `Provider unavailable: ${rawUrl}`,
+          cause: error
+        })
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: timeout,
+        orElse: () =>
+          Effect.fail(
+            TimeoutError.make({
+              duration: timeout
+            })
+          )
+      })
+    )
+  )
+
+const responseText = (response: Response): Effect.Effect<string, ParseError> =>
+  Effect.tryPromise({
+    try: () => response.text(),
+    catch: (error) =>
+      ParseError.make({
+        message: errorMessage(error),
+        raw: ""
+      })
+  })
+
+const retryAfter = (response: Response, fallback: Duration.Duration): Duration.Duration => {
+  const value = response.headers.get("Retry-After")?.trim()
+  return value !== undefined && /^\d+$/.test(value) ? Duration.seconds(Number(value)) : fallback
+}
+
+const classifyBodyResponse = (
+  response: Response,
+  url: string,
+  timeout: Duration.Duration,
+  accepts: (status: number) => boolean
+): Effect.Effect<string, LlmError> =>
+  Effect.flatMap(responseText(response), (body): Effect.Effect<string, LlmError> => {
+    const status = response.status
+    if (accepts(status)) {
+      return Effect.succeed(body)
+    }
+    if (status === 401 || status === 403) {
+      return Effect.fail(AuthenticationError.make({ message: url }))
+    }
+    if (status === 429) {
+      return Effect.fail(
+        RateLimitError.make({
+          retryAfter: retryAfter(response, timeout)
+        })
+      )
+    }
+    if (status >= 400 && status < 500) {
+      return Effect.fail(
+        InvalidRequestError.make({
+          message: `HTTP ${status}: ${body}`
+        })
+      )
+    }
+    return Effect.fail(
+      ProviderError.make({
+        message: `HTTP ${status}: ${body}`
+      })
+    )
+  })
+
+const requestHeaders = (
+  headers: Readonly<Record<string, string>>,
+  contentType: string | undefined
+): Headers => {
+  const result = new Headers(headers)
+  if (contentType !== undefined && !result.has("Content-Type")) {
+    result.set("Content-Type", contentType)
+  }
+  return result
+}
+
+const requestBody = (
+  method: string,
+  url: string,
+  body: string | undefined,
+  headers: Readonly<Record<string, string>>,
+  contentType: string | undefined,
+  timeout: Duration.Duration,
+  accepts: (status: number) => boolean
+): Effect.Effect<string, LlmError> =>
+  Effect.flatMap(
+    fetchResponse(
+      url,
+      {
+        method,
+        headers: requestHeaders(headers, contentType),
+        ...(body === undefined ? {} : { body })
+      },
+      timeout
+    ),
+    (response) => classifyBodyResponse(response, url, timeout, accepts)
+  )
+
+const streamBody = (
+  response: Response,
+  url: string,
+  timeout: Duration.Duration
+): Stream.Stream<string, LlmError> => {
+  if (response.status !== 200) {
+    return Stream.fromEffect(
+      classifyBodyResponse(response, url, timeout, (status) => status === 200)
+    )
+  }
+  const body = response.body
+  if (body === null) {
+    return Stream.fail(
+      ProviderError.make({
+        message: `Provider returned no streaming body: ${url}`
+      })
+    )
+  }
+
+  return Stream.fromReadableStream({
+    evaluate: () => body,
+    onError: (error) =>
+      ProviderError.make({
+        message: `Failed to read streaming response from ${url}`,
+        cause: error
+      })
+  }).pipe(
+    Stream.decodeText,
+    Stream.splitLines,
+    Stream.timeoutOrElse({
+      duration: timeout,
+      orElse: () =>
+        Stream.fail(
+          TimeoutError.make({
+            duration: timeout
+          })
+        )
+    })
+  )
+}
+
+const postJsonStream: HttpClientShape["postJsonStream"] = (url, body, headers, timeout) =>
+  Stream.unwrap(
+    Effect.map(
+      fetchResponse(
+        url,
+        {
+          method: "POST",
+          headers: requestHeaders(headers, "application/json"),
+          body
+        },
+        timeout
+      ),
+      (response) => streamBody(response, url, timeout)
+    )
+  )
+
+export const nodeHttpClient: HttpClientShape = makeHttpClient({
+  get: (url, headers, timeout) =>
+    requestBody("GET", url, undefined, headers, undefined, timeout, (status) => status === 200),
+  postJson: (url, body, headers, timeout) =>
+    requestBody(
+      "POST",
+      url,
+      body,
+      headers,
+      "application/json",
+      timeout,
+      (status) => status === 200
+    ),
+  send: (method, url, body, headers, contentType, timeout) =>
+    requestBody(
+      method,
+      url,
+      body,
+      headers,
+      contentType,
+      timeout,
+      (status) => status >= 200 && status < 300
+    ),
+  postJsonStream
+})
+
+export const NodeHttpClientLive = Layer.succeed(HttpClient)(nodeHttpClient)

package/src/NodePlainFileStore.ts

@@ -0,0 +1,75 @@
+import { createHash, randomUUID } from "node:crypto"
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { PlainFileStore, type PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { PersistenceError } from "@llm4ts/flow/FlowError"
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+const persistenceFailure =
+  (operation: string, path: string) =>
+  (error: unknown): PersistenceError =>
+    PersistenceError.make({
+      message: `failed to ${operation} ${path}: ${message(error)}`,
+      cause: error
+    })
+
+const ensureParent = async (path: string): Promise<void> => {
+  await mkdir(dirname(path), { recursive: true })
+}
+
+export const nodePlainFileStore: PlainFileStoreShape = {
+  read: (path) =>
+    Effect.tryPromise({
+      try: async () => {
+        try {
+          return await readFile(path, "utf8")
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return undefined
+          }
+          throw error
+        }
+      },
+      catch: persistenceFailure("read", path)
+    }),
+  writeAtomic: (path, contents) =>
+    Effect.tryPromise({
+      try: async () => {
+        await ensureParent(path)
+        const temporary = join(dirname(path), `.${randomUUID()}.llm4ts-tmp`)
+        try {
+          await writeFile(temporary, contents, "utf8")
+          await rename(temporary, path)
+        } finally {
+          await rm(temporary, { force: true })
+        }
+      },
+      catch: persistenceFailure("write", path)
+    }),
+  append: (path, contents) =>
+    Effect.tryPromise({
+      try: async () => {
+        await ensureParent(path)
+        await appendFile(path, contents, "utf8")
+      },
+      catch: persistenceFailure("append", path)
+    }),
+  remove: (path) =>
+    Effect.tryPromise({
+      try: () => rm(path, { force: true }),
+      catch: persistenceFailure("remove", path)
+    }),
+  hashSha256: (path) =>
+    Effect.tryPromise({
+      try: async () =>
+        createHash("sha256")
+          .update(await readFile(path))
+          .digest("hex"),
+      catch: persistenceFailure("hash", path)
+    })
+}
+
+export const NodePlainFileStoreLive = Layer.succeed(PlainFileStore)(nodePlainFileStore)

package/src/NodeProcessExecutor.ts

@@ -0,0 +1,331 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import * as readline from "node:readline"
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Queue from "effect/Queue"
+import * as Stream from "effect/Stream"
+import {
+  ProcessExecutor,
+  ProcessResult,
+  makeProcessExecutor,
+  type BidirectionalProcess,
+  type ProcessExecutorShape
+} from "@llm4ts/core/ProcessExecutor"
+import { InvalidRequestError, ProviderError, type LlmError } from "@llm4ts/core/Errors"
+
+const maxStderrLines = 256
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+const commandName = (argv: ReadonlyArray<string>): string => argv[0] ?? "process"
+
+const invalidArgv = (): InvalidRequestError => InvalidRequestError.make({ message: "empty argv" })
+
+const processFailure = (argv: ReadonlyArray<string>, detail: string): ProviderError =>
+  ProviderError.make({
+    message: detail.includes("ENOENT")
+      ? `${commandName(argv)} failed: command not found. Install '${commandName(argv)}' and make sure it is on your PATH` +
+        ` (coding-agent CLIs can be switched with LLM4TS_CODER)`
+      : `${commandName(argv)} failed: ${detail}`
+  })
+
+const spawnChild = (
+  argv: ReadonlyArray<string>,
+  cwd: string,
+  envVars: Readonly<Record<string, string>>
+): Effect.Effect<ChildProcessWithoutNullStreams, ProviderError> => {
+  const [command, ...args] = argv
+  if (command === undefined) {
+    return Effect.fail(
+      ProviderError.make({
+        message: "process failed: empty argv"
+      })
+    )
+  }
+
+  return Effect.try({
+    try: () =>
+      spawn(command, args, {
+        cwd,
+        env: {
+          ...process.env,
+          ...envVars
+        },
+        stdio: "pipe"
+      }),
+    catch: (error) => processFailure(argv, errorMessage(error))
+  })
+}
+
+const killChild = (child: ChildProcessWithoutNullStreams): Effect.Effect<void> =>
+  Effect.sync(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill("SIGKILL")
+    }
+  })
+
+const writeAndCloseStdin = (
+  child: ChildProcessWithoutNullStreams,
+  stdin: string | undefined
+): void => {
+  if (stdin === undefined) {
+    child.stdin.end()
+  } else {
+    child.stdin.end(stdin)
+  }
+}
+
+const awaitCapturedProcess = (
+  child: ChildProcessWithoutNullStreams,
+  argv: ReadonlyArray<string>,
+  stdin: string | undefined
+): Effect.Effect<ProcessResult, ProviderError> =>
+  Effect.callback((resume) => {
+    const stdout: Array<string> = []
+    const stderr: Array<string> = []
+    const outLines = readline.createInterface({ input: child.stdout })
+    const errLines = readline.createInterface({ input: child.stderr })
+
+    const onStdout = (line: string): void => {
+      stdout.push(line)
+    }
+    const onStderr = (line: string): void => {
+      stderr.push(line)
+    }
+    const onError = (error: Error): void => {
+      resume(Effect.fail(processFailure(argv, error.message)))
+    }
+    const onClose = (exitCode: number | null): void => {
+      resume(
+        Effect.succeed(
+          ProcessResult.make({
+            stdout,
+            stderr,
+            exitCode: exitCode ?? -1
+          })
+        )
+      )
+    }
+
+    outLines.on("line", onStdout)
+    errLines.on("line", onStderr)
+    child.once("error", onError)
+    child.once("close", onClose)
+    writeAndCloseStdin(child, stdin)
+
+    return Effect.sync(() => {
+      child.off("error", onError)
+      child.off("close", onClose)
+      outLines.close()
+      errLines.close()
+    })
+  })
+
+const runCaptured = (
+  argv: ReadonlyArray<string>,
+  cwd: string,
+  envVars: Readonly<Record<string, string>>,
+  stdin: string | undefined
+): Effect.Effect<ProcessResult, LlmError> => {
+  if (argv.length === 0) {
+    return Effect.fail(invalidArgv())
+  }
+
+  return Effect.acquireUseRelease(
+    spawnChild(argv, cwd, envVars),
+    (child) => awaitCapturedProcess(child, argv, stdin),
+    (child) => killChild(child)
+  )
+}
+
+interface StreamOptions {
+  readonly stdin: string | undefined
+  readonly killOnClose: boolean
+  readonly failOnNonZero: boolean
+}
+
+const childLines = (
+  child: ChildProcessWithoutNullStreams,
+  argv: ReadonlyArray<string>,
+  options: StreamOptions
+): Stream.Stream<string, LlmError> =>
+  Stream.callback<string, LlmError>((queue) =>
+    Effect.gen(function* () {
+      const stderr: Array<string> = []
+      const outLines = readline.createInterface({ input: child.stdout })
+      const errLines = readline.createInterface({ input: child.stderr })
+
+      const onStdout = (line: string): void => {
+        Queue.offerUnsafe(queue, line)
+      }
+      const onStderr = (line: string): void => {
+        if (stderr.length < maxStderrLines) {
+          stderr.push(line)
+        }
+      }
+      const onError = (error: Error): void => {
+        Queue.failCauseUnsafe(queue, Cause.fail(processFailure(argv, error.message)))
+      }
+      const onClose = (exitCode: number | null): void => {
+        if (options.failOnNonZero && exitCode !== 0) {
+          const detail = `${commandName(argv)} exited with code ${exitCode ?? -1}${
+            stderr.length === 0 ? "" : `: ${stderr.join("\n")}`
+          }`
+          Queue.failCauseUnsafe(queue, Cause.fail(processFailure(argv, detail)))
+        } else {
+          Queue.endUnsafe(queue)
+        }
+      }
+
+      outLines.on("line", onStdout)
+      errLines.on("line", onStderr)
+      child.once("error", onError)
+      child.once("close", onClose)
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          child.off("error", onError)
+          child.off("close", onClose)
+          outLines.close()
+          errLines.close()
+        }).pipe(Effect.andThen(options.killOnClose ? killChild(child) : Effect.void))
+      )
+    })
+  )
+
+const runStreaming = (
+  argv: ReadonlyArray<string>,
+  cwd: string,
+  envVars: Readonly<Record<string, string>>,
+  stdin: string | undefined
+): Stream.Stream<string, LlmError> => {
+  if (argv.length === 0) {
+    return Stream.fail(invalidArgv())
+  }
+
+  return Stream.callback<string, LlmError>((queue) =>
+    Effect.gen(function* () {
+      const child = yield* Effect.acquireRelease(spawnChild(argv, cwd, envVars), (process) =>
+        killChild(process)
+      )
+      const stderr: Array<string> = []
+      const outLines = readline.createInterface({ input: child.stdout })
+      const errLines = readline.createInterface({ input: child.stderr })
+
+      const onStdout = (line: string): void => {
+        Queue.offerUnsafe(queue, line)
+      }
+      const onStderr = (line: string): void => {
+        if (stderr.length < maxStderrLines) {
+          stderr.push(line)
+        }
+      }
+      const onError = (error: Error): void => {
+        Queue.failCauseUnsafe(queue, Cause.fail(processFailure(argv, error.message)))
+      }
+      const onClose = (exitCode: number | null): void => {
+        if (exitCode === 0) {
+          Queue.endUnsafe(queue)
+        } else {
+          const detail = `${commandName(argv)} exited with code ${exitCode ?? -1}${
+            stderr.length === 0 ? "" : `: ${stderr.join("\n")}`
+          }`
+          Queue.failCauseUnsafe(queue, Cause.fail(processFailure(argv, detail)))
+        }
+      }
+
+      outLines.on("line", onStdout)
+      errLines.on("line", onStderr)
+      child.once("error", onError)
+      child.once("close", onClose)
+      writeAndCloseStdin(child, stdin)
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          child.off("error", onError)
+          child.off("close", onClose)
+          outLines.close()
+          errLines.close()
+        })
+      )
+    })
+  )
+}
+
+const writeLine = (
+  child: ChildProcessWithoutNullStreams,
+  argv: ReadonlyArray<string>,
+  line: string
+): Effect.Effect<void, ProviderError> =>
+  Effect.callback((resume) => {
+    const onError = (error: Error): void => {
+      resume(Effect.fail(processFailure(argv, error.message)))
+    }
+    child.stdin.once("error", onError)
+    child.stdin.write(`${line}\n`, (error) => {
+      child.stdin.off("error", onError)
+      resume(
+        error === null || error === undefined
+          ? Effect.void
+          : Effect.fail(processFailure(argv, error.message))
+      )
+    })
+    return Effect.sync(() => {
+      child.stdin.off("error", onError)
+    })
+  })
+
+const bidirectionalBundle = (
+  stdin: Queue.Queue<string>,
+  stdout: Stream.Stream<string, LlmError>
+): BidirectionalProcess => [stdin, stdout]
+
+const runBidirectional: ProcessExecutorShape["runBidirectional"] = (argv, cwd, envVars) => {
+  if (argv.length === 0) {
+    return Effect.fail(invalidArgv())
+  }
+
+  return Effect.gen(function* () {
+    const input = yield* Effect.acquireRelease(Queue.unbounded<string>(), (queue) =>
+      Queue.shutdown(queue).pipe(Effect.asVoid)
+    )
+    const child = yield* Effect.acquireRelease(spawnChild(argv, cwd, envVars), (process) =>
+      killChild(process)
+    )
+
+    const pump = Effect.suspend(function loop(): Effect.Effect<void, ProviderError> {
+      return Effect.flatMap(Queue.take(input), (line) =>
+        writeLine(child, argv, line).pipe(Effect.andThen(Effect.suspend(loop)))
+      )
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          child.stdin.end()
+        })
+      ),
+      Effect.catchCause(() => Effect.void)
+    )
+    yield* Effect.forkScoped(pump)
+
+    return bidirectionalBundle(
+      input,
+      childLines(child, argv, {
+        stdin: undefined,
+        killOnClose: false,
+        failOnNonZero: false
+      })
+    )
+  })
+}
+
+export const nodeProcessExecutor: ProcessExecutorShape = makeProcessExecutor({
+  run: (argv, cwd, envVars) => runCaptured(argv, cwd, envVars, undefined),
+  runStreaming: (argv, cwd, envVars) => runStreaming(argv, cwd, envVars, undefined),
+  runWithStdin: (argv, cwd, envVars, stdin) => runCaptured(argv, cwd, envVars, stdin),
+  runStreamingWithStdin: (argv, cwd, envVars, stdin) => runStreaming(argv, cwd, envVars, stdin),
+  runBidirectional
+})
+
+export const NodeProcessExecutorLive = Layer.succeed(ProcessExecutor)(nodeProcessExecutor)

package/src/NodeRuntime.ts

@@ -0,0 +1,19 @@
+import * as Layer from "effect/Layer"
+import { ConnectorRegistryLive } from "@llm4ts/core/providers/ConnectorFactories"
+import { NodeHttpClientLive } from "./NodeHttpClient.ts"
+import { NodeGeminiCliExecutorLive } from "./NodeGeminiCliExecutor.ts"
+import { NodePlainFileStoreLive } from "./NodePlainFileStore.ts"
+import { NodeProcessExecutorLive } from "./NodeProcessExecutor.ts"
+import { NodeTemporaryFilesLive } from "./NodeTemporaryFiles.ts"
+
+export const NodeBoundaryLayers = Layer.mergeAll(
+  NodeHttpClientLive,
+  NodeProcessExecutorLive,
+  NodeTemporaryFilesLive,
+  NodeGeminiCliExecutorLive,
+  NodePlainFileStoreLive
+)
+
+const NodeConnectorRegistryLive = ConnectorRegistryLive.pipe(Layer.provide(NodeBoundaryLayers))
+
+export const NodeRuntimeLive = Layer.merge(NodeBoundaryLayers, NodeConnectorRegistryLive)