@llm4ts/runner 0.1.0

package/src/NodeTemporaryFiles.ts

@@ -0,0 +1,46 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { TemporaryFiles, type TemporaryFilesShape } from "@llm4ts/core/TemporaryFiles"
+import { ProviderError } from "@llm4ts/core/Errors"
+
+interface TemporaryFile {
+  readonly directory: string
+  readonly path: string
+}
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+export const nodeTemporaryFiles: TemporaryFilesShape = {
+  write: (prefix, suffix, contents) =>
+    Effect.acquireRelease(
+      Effect.tryPromise({
+        try: async (): Promise<TemporaryFile> => {
+          const directory = await mkdtemp(join(tmpdir(), prefix))
+          const path = join(directory, `value${suffix}`)
+          await writeFile(path, contents, "utf8")
+          return {
+            directory,
+            path
+          }
+        },
+        catch: (error) =>
+          ProviderError.make({
+            message: `Failed to create temporary file: ${errorMessage(error)}`,
+            cause: error
+          })
+      }),
+      ({ directory }) =>
+        Effect.promise(() =>
+          rm(directory, {
+            recursive: true,
+            force: true
+          })
+        ).pipe(Effect.catchCause(() => Effect.void))
+    ).pipe(Effect.map(({ path }) => path))
+}
+
+export const NodeTemporaryFilesLive = Layer.succeed(TemporaryFiles, nodeTemporaryFiles)

package/src/NodeWorkspace.ts

@@ -0,0 +1,282 @@
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  stat,
+  writeFile,
+  appendFile
+} from "node:fs/promises"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import {
+  SearchMatch,
+  Workspace,
+  defaultWorkspaceLimits,
+  type WorkspaceError,
+  type WorkspaceLimits,
+  type WorkspaceShape
+} from "@llm4ts/flow/Workspace"
+import { WorkspaceIoError, WorkspaceLimitError, WorkspacePathError } from "@llm4ts/flow/FlowError"
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+const isMissing = (error: unknown): boolean =>
+  error instanceof Error && "code" in error && error.code === "ENOENT"
+
+const contains = (root: string, target: string): boolean => {
+  const path = relative(root, target)
+  return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path))
+}
+
+const globRegex = (glob: string): RegExp => {
+  let source = ""
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob.charAt(index)
+    if (character === "*" && glob.charAt(index + 1) === "*") {
+      source += ".*"
+      index += 1
+    } else if (character === "*") {
+      source += "[^/]*"
+    } else if (character === "?") {
+      source += "[^/]"
+    } else {
+      source += character.replace(/[\\^$.[\]{}()+|]/g, "\\$&")
+    }
+  }
+  return new RegExp(`^${source}$`)
+}
+
+const nearestExistingParent = async (path: string): Promise<string> => {
+  let current = path
+  while (true) {
+    try {
+      await lstat(current)
+      return current
+    } catch (error) {
+      if (!isMissing(error)) {
+        throw error
+      }
+      const parent = dirname(current)
+      if (parent === current) {
+        throw error
+      }
+      current = parent
+    }
+  }
+}
+
+export const makeNodeWorkspace = Effect.fn("@llm4ts/runner/NodeWorkspace.make")(function* (
+  configuredRoot: string,
+  limits: WorkspaceLimits = defaultWorkspaceLimits
+): Effect.fn.Return<WorkspaceShape, WorkspaceError> {
+  const root = yield* Effect.tryPromise({
+    try: () => realpath(resolve(configuredRoot)),
+    catch: (error) =>
+      WorkspaceIoError.make({
+        operation: "open workspace",
+        path: configuredRoot,
+        message: errorMessage(error),
+        cause: error
+      })
+  })
+
+  const resolveSafe = (input: string): Effect.Effect<string, WorkspaceError> =>
+    Effect.tryPromise({
+      try: async () => {
+        const lexical = resolve(root, input)
+        if (!contains(root, lexical)) {
+          throw WorkspacePathError.make({
+            path: input,
+            message: "path escapes the configured workspace"
+          })
+        }
+        const existing = await nearestExistingParent(lexical)
+        const physical = await realpath(existing)
+        if (!contains(root, physical)) {
+          throw WorkspacePathError.make({
+            path: input,
+            message: "path resolves through a symlink outside the configured workspace"
+          })
+        }
+        return lexical
+      },
+      catch: (error) =>
+        error instanceof WorkspacePathError
+          ? error
+          : WorkspaceIoError.make({
+              operation: "resolve",
+              path: input,
+              message: errorMessage(error),
+              cause: error
+            })
+    })
+
+  const read = Effect.fn("@llm4ts/runner/NodeWorkspace.read")(function* (
+    input: string
+  ): Effect.fn.Return<string, WorkspaceError> {
+    const path = yield* resolveSafe(input)
+    const info = yield* Effect.tryPromise({
+      try: () => stat(path),
+      catch: (error) =>
+        WorkspaceIoError.make({
+          operation: "read",
+          path: input,
+          message: errorMessage(error),
+          cause: error
+        })
+    })
+    if (info.size > limits.maxReadBytes) {
+      return yield* WorkspaceLimitError.make({
+        operation: "read bytes",
+        limit: limits.maxReadBytes,
+        actual: info.size
+      })
+    }
+    return yield* Effect.tryPromise({
+      try: () => readFile(path, "utf8"),
+      catch: (error) =>
+        WorkspaceIoError.make({
+          operation: "read",
+          path: input,
+          message: errorMessage(error),
+          cause: error
+        })
+    })
+  })
+
+  const writeBounded = (
+    operation: "write" | "append",
+    input: string,
+    contents: string
+  ): Effect.Effect<void, WorkspaceError> =>
+    Effect.gen(function* () {
+      const bytes = Buffer.byteLength(contents)
+      if (bytes > limits.maxWriteBytes) {
+        return yield* WorkspaceLimitError.make({
+          operation: `${operation} bytes`,
+          limit: limits.maxWriteBytes,
+          actual: bytes
+        })
+      }
+      const path = yield* resolveSafe(input)
+      yield* Effect.tryPromise({
+        try: async () => {
+          await mkdir(dirname(path), { recursive: true })
+          if (operation === "write") {
+            await writeFile(path, contents, "utf8")
+          } else {
+            await appendFile(path, contents, "utf8")
+          }
+        },
+        catch: (error) =>
+          WorkspaceIoError.make({
+            operation,
+            path: input,
+            message: errorMessage(error),
+            cause: error
+          })
+      })
+    })
+
+  const discover = (pattern = "**/*"): Effect.Effect<ReadonlyArray<string>, WorkspaceError> =>
+    Effect.tryPromise({
+      try: async () => {
+        const normalizedPattern = pattern.replaceAll("\\", "/")
+        const matcher = normalizedPattern === "**/*" ? /.*/ : globRegex(normalizedPattern)
+        const results: Array<string> = []
+        const walk = async (directory: string, depth: number): Promise<void> => {
+          if (depth > limits.maxDepth) {
+            throw WorkspaceLimitError.make({
+              operation: "discovery depth",
+              limit: limits.maxDepth,
+              actual: depth
+            })
+          }
+          const entries = await readdir(directory, { withFileTypes: true })
+          entries.sort((left, right) => left.name.localeCompare(right.name))
+          for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+              continue
+            }
+            const absolute = resolve(directory, entry.name)
+            const path = relative(root, absolute).split(sep).join("/")
+            if (entry.isDirectory()) {
+              await walk(absolute, depth + 1)
+            } else if (entry.isFile() && matcher.test(path)) {
+              results.push(path)
+              if (results.length > limits.maxResults) {
+                throw WorkspaceLimitError.make({
+                  operation: "discovery results",
+                  limit: limits.maxResults,
+                  actual: results.length
+                })
+              }
+            }
+          }
+        }
+        await walk(root, 0)
+        return results
+      },
+      catch: (error) =>
+        error instanceof WorkspaceLimitError
+          ? error
+          : WorkspaceIoError.make({
+              operation: "discover",
+              path: root,
+              message: errorMessage(error),
+              cause: error
+            })
+    })
+
+  const search = Effect.fn("@llm4ts/runner/NodeWorkspace.search")(function* (
+    query: string,
+    pattern = "**/*"
+  ): Effect.fn.Return<ReadonlyArray<SearchMatch>, WorkspaceError> {
+    const paths = yield* discover(pattern)
+    const matches: Array<SearchMatch> = []
+    for (const path of paths) {
+      const text = yield* read(path)
+      const lines = text.split("\n")
+      for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? ""
+        if (line.includes(query)) {
+          matches.push(
+            SearchMatch.make({
+              path,
+              line: index + 1,
+              text: line
+            })
+          )
+          if (matches.length > limits.maxResults) {
+            return yield* WorkspaceLimitError.make({
+              operation: "search results",
+              limit: limits.maxResults,
+              actual: matches.length
+            })
+          }
+        }
+      }
+    }
+    return matches
+  })
+
+  return {
+    root,
+    resolve: resolveSafe,
+    read,
+    write: (path, contents) => writeBounded("write", path, contents),
+    append: (path, contents) => writeBounded("append", path, contents),
+    discover,
+    search
+  }
+})
+
+export const NodeWorkspaceLive = (
+  root: string,
+  limits: WorkspaceLimits = defaultWorkspaceLimits
+): Layer.Layer<Workspace, WorkspaceError> =>
+  Layer.effect(Workspace, makeNodeWorkspace(root, limits))

package/src/Package.ts

@@ -0,0 +1 @@
+export const packageName = "@llm4ts/runner"

package/src/ReviewFingerprint.ts

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto"
+
+export const reviewFingerprint = (...parts: ReadonlyArray<string>): string => {
+  const digest = createHash("sha256")
+  for (const part of parts) {
+    const bytes = Buffer.from(part, "utf8")
+    const length = Buffer.alloc(4)
+    length.writeUInt32BE(bytes.length)
+    digest.update(length)
+    digest.update(bytes)
+  }
+  return digest.digest("hex")
+}

package/src/Terminal.ts

@@ -0,0 +1,329 @@
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Semaphore from "effect/Semaphore"
+import type * as Scope from "effect/Scope"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import type { FlowEvent, FlowEventHub } from "@llm4ts/flow/FlowEvents"
+
+export const Verbosity = Schema.Literals(["Quiet", "Normal", "Verbose", "Debug"])
+export type Verbosity = typeof Verbosity.Type
+
+export const parseVerbosity = (value: string | undefined): Verbosity => {
+  switch (value?.trim().toLowerCase()) {
+    case "quiet":
+      return "Quiet"
+    case "verbose":
+      return "Verbose"
+    case "debug":
+      return "Debug"
+    default:
+      return "Normal"
+  }
+}
+
+export const rendersEvent = (verbosity: Verbosity, event: FlowEvent): boolean => {
+  switch (event._tag) {
+    case "StageStarted":
+    case "StageCompleted":
+    case "StageFailed":
+    case "Aborted":
+    case "CapabilityDenied":
+    case "CapabilityUnenforceable":
+      return true
+    case "TokensUsed":
+      return verbosity === "Verbose" || verbosity === "Debug"
+    default:
+      return verbosity !== "Quiet"
+  }
+}
+
+export const terminalSafe = (value: string): string => {
+  let safe = ""
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index)
+    const escapedCsi = code === 27 && value.charAt(index + 1) === "["
+    if (escapedCsi || code === 155) {
+      index += escapedCsi ? 2 : 1
+      while (index < value.length) {
+        const terminator = value.charCodeAt(index)
+        if (terminator >= 64 && terminator <= 126) {
+          break
+        }
+        index += 1
+      }
+      continue
+    }
+    const escapedOsc = code === 27 && value.charAt(index + 1) === "]"
+    if (escapedOsc || code === 157) {
+      index += escapedOsc ? 2 : 1
+      while (index < value.length) {
+        const current = value.charCodeAt(index)
+        if (current === 7) {
+          break
+        }
+        if (current === 27 && value.charAt(index + 1) === "\\") {
+          index += 1
+          break
+        }
+        index += 1
+      }
+      continue
+    }
+    const allowedWhitespace = code === 9 || code === 10 || code === 13
+    if (allowedWhitespace || (code >= 32 && !(code >= 127 && code <= 159))) {
+      safe += value.charAt(index)
+    }
+  }
+  return safe
+}
+
+const Ansi = Object.freeze({
+  reset: "\u001b[0m",
+  boldMagenta: "\u001b[1;35m",
+  green: "\u001b[32m",
+  red: "\u001b[31m",
+  yellowBold: "\u001b[1;33m",
+  darkGray: "\u001b[90m"
+})
+
+export interface TerminalPalette {
+  readonly enabled: boolean
+  readonly stageStart: (label: string) => string
+  readonly stageDone: (label: string) => string
+  readonly fail: (label: string) => string
+  readonly info: (label: string) => string
+  readonly assistant: (text: string) => string
+  readonly toolCall: (tool: string, args: string) => string
+  readonly status: (frame: string, label: string) => string
+}
+
+export const makeTerminalPalette = (enabled: boolean): TerminalPalette => {
+  const paint = (code: string, text: string): string =>
+    enabled ? `${code}${text}${Ansi.reset}` : text
+  return {
+    enabled,
+    stageStart: (label) => `${paint(Ansi.boldMagenta, "▶ ")}${label}`,
+    stageDone: (label) => `${paint(Ansi.green, "✔ ")}${label}`,
+    fail: (label) => `${paint(Ansi.red, "✖ ")}${label}`,
+    info: (label) => paint(Ansi.darkGray, `· ${label}`),
+    assistant: (text) => `${paint(Ansi.boldMagenta, "● ")}${text}`,
+    toolCall: (tool, args) => {
+      const head = paint(Ansi.yellowBold, `● ${tool}`)
+      return args.length === 0 ? head : `${head} ${paint(Ansi.darkGray, args)}`
+    },
+    status: (frame, label) => `${paint(Ansi.boldMagenta, frame)} ${label}`
+  }
+}
+
+export const plainTerminalPalette = makeTerminalPalette(false)
+
+export const terminalLine = (
+  event: FlowEvent,
+  palette: TerminalPalette = plainTerminalPalette
+): string => {
+  const safe = terminalSafe
+  switch (event._tag) {
+    case "StageStarted":
+      return palette.stageStart(safe(event.stage))
+    case "StageCompleted":
+      return palette.stageDone(safe(event.stage))
+    case "StageFailed":
+      return palette.fail(`${safe(event.stage)} — ${safe(event.message)}`)
+    case "Aborted":
+      return palette.fail(`aborted: ${safe(event.message)}`)
+    case "Info":
+      return palette.info(safe(event.message))
+    case "ToolUse":
+      return palette.toolCall(safe(event.tool), safe(event.args))
+    case "AssistantMessage":
+      return palette.assistant(safe(event.text).trim())
+    case "TokensUsed":
+      return palette.info(
+        `tokens: ${safe(event.agent)} ${event.usage.prompt} in / ${event.usage.completion} out`
+      )
+    case "CapabilityUsed":
+      return palette.info(`capability ${safe(event.capability)}: ${safe(event.operation)}`)
+    case "CapabilityDenied":
+      return palette.fail(
+        `capability denied: ${safe(event.capability)} for ${safe(event.operation)}`
+      )
+    case "CapabilityUnenforceable":
+      return palette.fail(`capability unenforceable: ${safe(event.detail)}`)
+    case "Declassified":
+      return palette.info(`declassified: ${safe(event.label)}`)
+  }
+}
+
+export const indentBlock = (depth: number, rendered: string): string => {
+  const padding = "  ".repeat(Math.max(0, depth))
+  const lines = rendered.split("\n")
+  return lines.map((line, index) => `${padding}${index === 0 ? "" : "  "}${line}`).join("\n")
+}
+
+const closesChild = (event: FlowEvent): boolean =>
+  event._tag === "StageCompleted" || event._tag === "StageFailed" || event._tag === "Aborted"
+
+export const indentDepths = (events: ReadonlyArray<FlowEvent>): ReadonlyArray<number> => {
+  let depth = 0
+  return events.map((event) => {
+    if (closesChild(event)) {
+      depth = Math.max(0, depth - 1)
+      return depth
+    }
+    const current = depth
+    if (event._tag === "StageStarted") {
+      depth += 1
+    }
+    return current
+  })
+}
+
+export interface TerminalSurface {
+  readonly palette: TerminalPalette
+  readonly log: (line: string) => Effect.Effect<void>
+  readonly setStatus: (label: string | undefined) => Effect.Effect<void>
+  readonly suspend: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+}
+
+export const makePlainTerminalSurface = (
+  write: (line: string) => void = (line) => process.stdout.write(`${line}\n`)
+): TerminalSurface => ({
+  palette: plainTerminalPalette,
+  log: (line) => Effect.sync(() => write(line)),
+  setStatus: (_label) => Effect.void,
+  suspend: (effect) => effect
+})
+
+const spinnerFrames = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"])
+const clearLine = "\r\u001b[2K"
+
+export interface TerminalOutput {
+  readonly isTTY?: boolean
+  readonly write: (text: string) => unknown
+}
+
+export const terminalSupportsColor = (
+  output: TerminalOutput,
+  environment: Readonly<Record<string, string | undefined>>
+): boolean => output.isTTY === true && environment.NO_COLOR === undefined
+
+export const makeLiveTerminalSurface = Effect.fn("@llm4ts/runner/Terminal.makeLive")(function* (
+  write: (text: string) => void = (text) => {
+    process.stdout.write(text)
+  },
+  palette: TerminalPalette = makeTerminalPalette(true),
+  tick: Duration.Input = "100 millis"
+): Effect.fn.Return<TerminalSurface, never, Scope.Scope> {
+  const lock = yield* Semaphore.make(1)
+  const status = yield* Ref.make<string | undefined>(undefined)
+  const frame = yield* Ref.make(0)
+  const suspended = yield* Ref.make(false)
+  const emit = (text: string): Effect.Effect<void> => Effect.sync(() => write(text))
+  const drawStatus = Effect.gen(function* () {
+    if (yield* Ref.get(suspended)) {
+      return
+    }
+    const label = yield* Ref.get(status)
+    if (label !== undefined) {
+      const currentFrame = yield* Ref.get(frame)
+      yield* emit(
+        `${clearLine}${palette.status(spinnerFrames[currentFrame % spinnerFrames.length], label)}`
+      )
+    }
+  })
+  const surface: TerminalSurface = {
+    palette,
+    log: (line) =>
+      lock.withPermit(
+        emit(clearLine).pipe(Effect.andThen(emit(`${line}\n`)), Effect.andThen(drawStatus))
+      ),
+    setStatus: (label) =>
+      lock.withPermit(
+        Ref.set(status, label).pipe(Effect.andThen(emit(clearLine)), Effect.andThen(drawStatus))
+      ),
+    suspend: (effect) =>
+      lock
+        .withPermit(Ref.set(suspended, true).pipe(Effect.andThen(emit(clearLine))))
+        .pipe(
+          Effect.andThen(effect),
+          Effect.ensuring(
+            lock.withPermit(Ref.set(suspended, false).pipe(Effect.andThen(drawStatus)))
+          )
+        )
+  }
+  yield* Effect.sleep(tick).pipe(
+    Effect.andThen(Ref.update(frame, (current) => current + 1)),
+    Effect.andThen(lock.withPermit(drawStatus)),
+    Effect.forever,
+    Effect.forkScoped
+  )
+  yield* Effect.addFinalizer(() => lock.withPermit(emit(clearLine)))
+  return surface
+})
+
+export const makeTerminalSurface = (
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  output: TerminalOutput = process.stdout
+): Effect.Effect<TerminalSurface, never, Scope.Scope> => {
+  const write = (text: string): void => {
+    output.write(text)
+  }
+  return terminalSupportsColor(output, environment)
+    ? makeLiveTerminalSurface(write)
+    : Effect.succeed(makePlainTerminalSurface((line) => write(`${line}\n`)))
+}
+
+export interface TerminalConsumer {
+  readonly consumed: Ref.Ref<number>
+  readonly awaitDrained: (timeout?: Duration.Input) => Effect.Effect<void>
+}
+
+export const consumeTerminalEvents = Effect.fn("@llm4ts/runner/Terminal.consume")(function* (
+  events: FlowEventHub,
+  surface: TerminalSurface,
+  verbosity: Verbosity = "Normal"
+): Effect.fn.Return<TerminalConsumer, never, Scope.Scope> {
+  const depth = yield* Ref.make(0)
+  const stages = yield* Ref.make<ReadonlyArray<string>>([])
+  const consumed = yield* Ref.make(0)
+  const subscription = yield* events.subscribe
+  const palette = surface.palette
+  yield* Stream.fromSubscription(subscription).pipe(
+    Stream.runForEach((event) =>
+      Effect.gen(function* () {
+        const currentDepth = closesChild(event)
+          ? yield* Ref.updateAndGet(depth, (value) => Math.max(0, value - 1))
+          : yield* Ref.get(depth)
+        if (event._tag === "StageStarted") {
+          yield* Ref.update(depth, (value) => value + 1)
+          const active = terminalSafe(event.stage)
+          yield* Ref.update(stages, (current) => [...current, active])
+          yield* surface.setStatus(active)
+        } else if (closesChild(event)) {
+          const remaining = yield* Ref.updateAndGet(stages, (current) => current.slice(0, -1))
+          yield* surface.setStatus(remaining.at(-1))
+        }
+        if (rendersEvent(verbosity, event)) {
+          yield* surface.log(indentBlock(currentDepth, terminalLine(event, palette)))
+        }
+        yield* Ref.update(consumed, (count) => count + 1)
+      })
+    ),
+    Effect.forkScoped
+  )
+  const awaitDrained = (timeout: Duration.Input = "3 seconds"): Effect.Effect<void> =>
+    Effect.gen(function* () {
+      const target = yield* events.publishedCount
+      const drain: Effect.Effect<void> = Effect.suspend(() =>
+        Ref.get(consumed).pipe(
+          Effect.flatMap((count) =>
+            count >= target ? Effect.void : Effect.yieldNow.pipe(Effect.andThen(drain))
+          )
+        )
+      )
+      yield* Effect.timeoutOption(drain, timeout)
+    })
+  return { consumed, awaitDrained }
+})