@llm4ts/flow 0.1.0

package/src/TransientRetry.ts

@@ -0,0 +1,238 @@
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
+import type { LlmError } from "@llm4ts/core/Errors"
+import { LlmService, type LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { LlmChunk } from "@llm4ts/core/Models"
+import { FlowEvents, Info } from "./FlowEvents.ts"
+
+const transientSignals: ReadonlyArray<string> = [
+  "connection reset",
+  "server_error",
+  "internal error",
+  "service unavailable",
+  "unavailable",
+  "overloaded",
+  "temporarily",
+  "timed out",
+  "api error",
+  "unknown error",
+  "code=500",
+  "code=502",
+  "code=503",
+  "code=504",
+  " 500",
+  " 502",
+  " 503",
+  " 504"
+]
+
+const flakyStreamSignals: ReadonlyArray<string> = [
+  "empty response",
+  "malformed tool call",
+  "invalid stream"
+]
+
+const includesSignal = (message: string, signals: ReadonlyArray<string>): boolean => {
+  const normalized = message.toLowerCase()
+  return signals.some((signal) => normalized.includes(signal))
+}
+
+export const isFlakyStream = (error: LlmError): boolean =>
+  error._tag === "ProviderError" && includesSignal(error.message, flakyStreamSignals)
+
+export const isTransient = (error: LlmError): boolean => {
+  switch (error._tag) {
+    case "TimeoutError":
+    case "RateLimitError":
+      return true
+    case "ProviderError":
+      return !isFlakyStream(error) && includesSignal(error.message, transientSignals)
+    default:
+      return false
+  }
+}
+
+const maxHonoredRetryAfter = Duration.minutes(2)
+
+export const transientDelay = (error: LlmError, backoff: Duration.Duration): Duration.Duration => {
+  if (error._tag !== "RateLimitError" || error.retryAfter === undefined) {
+    return backoff
+  }
+
+  return Duration.max(backoff, Duration.min(error.retryAfter, maxHonoredRetryAfter))
+}
+
+export interface TransientRetryOptions {
+  readonly maxRetries?: number
+  readonly baseDelay?: Duration.Input
+  readonly flakyRetries?: number
+  readonly flakyDelay?: Duration.Input
+}
+
+interface ResolvedTransientRetryOptions {
+  readonly maxRetries: number
+  readonly baseDelay: Duration.Duration
+  readonly flakyRetries: number
+  readonly flakyDelay: Duration.Duration
+}
+
+const resolveOptions = (options: TransientRetryOptions): ResolvedTransientRetryOptions => ({
+  maxRetries: options.maxRetries ?? 3,
+  baseDelay: Duration.fromInputUnsafe(options.baseDelay ?? "1 second"),
+  flakyRetries: options.flakyRetries ?? 6,
+  flakyDelay: Duration.fromInputUnsafe(options.flakyDelay ?? "1 second")
+})
+
+const backoff = (baseDelay: Duration.Duration, attempt: number): Duration.Duration =>
+  Duration.times(baseDelay, 2 ** attempt)
+
+const retryNotice = (
+  events: FlowEvents["Service"],
+  what: string,
+  attempt: number,
+  maximum: number,
+  error: LlmError
+): Effect.Effect<void> =>
+  events.publish(
+    Info.make({
+      message: `⟳ ${what} — retry ${attempt + 1}/${maximum}: ${error.message}`
+    })
+  )
+
+const waitForRetry = (
+  events: FlowEvents["Service"],
+  what: string,
+  attempt: number,
+  maximum: number,
+  error: LlmError,
+  delay: Duration.Duration
+): Effect.Effect<void> =>
+  retryNotice(events, what, attempt, maximum, error).pipe(Effect.andThen(Effect.sleep(delay)))
+
+const retryEffect = <A, R>(
+  effect: Effect.Effect<A, LlmError, R>,
+  what: string,
+  options: ResolvedTransientRetryOptions,
+  events: FlowEvents["Service"]
+): Effect.Effect<A, LlmError, R> => {
+  const loop = (transientAttempt: number, flakyAttempt: number): Effect.Effect<A, LlmError, R> =>
+    Effect.catchIf(
+      effect,
+      () => true,
+      (error) => {
+        if (isFlakyStream(error) && flakyAttempt < options.flakyRetries) {
+          return waitForRetry(
+            events,
+            `flaky ${what} (fresh retry)`,
+            flakyAttempt,
+            options.flakyRetries,
+            error,
+            options.flakyDelay
+          ).pipe(Effect.andThen(Effect.suspend(() => loop(transientAttempt, flakyAttempt + 1))))
+        }
+
+        if (isTransient(error) && transientAttempt < options.maxRetries) {
+          return waitForRetry(
+            events,
+            `transient error (${what})`,
+            transientAttempt,
+            options.maxRetries,
+            error,
+            transientDelay(error, backoff(options.baseDelay, transientAttempt))
+          ).pipe(Effect.andThen(Effect.suspend(() => loop(transientAttempt + 1, flakyAttempt))))
+        }
+
+        return Effect.fail(error)
+      }
+    )
+
+  return loop(0, 0)
+}
+
+const retryStream = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  what: string,
+  options: ResolvedTransientRetryOptions,
+  events: FlowEvents["Service"]
+): Stream.Stream<LlmChunk, LlmError, R> => {
+  const waitThenRetry = (
+    notice: Effect.Effect<void>,
+    next: () => Stream.Stream<LlmChunk, LlmError, R>
+  ): Stream.Stream<LlmChunk, LlmError, R> =>
+    Stream.concat(Stream.drain(Stream.fromEffect(notice)), Stream.suspend(next))
+
+  const loop = (
+    transientAttempt: number,
+    flakyAttempt: number
+  ): Stream.Stream<LlmChunk, LlmError, R> =>
+    Stream.catchIf(
+      stream,
+      () => true,
+      (error) => {
+        if (isFlakyStream(error) && flakyAttempt < options.flakyRetries) {
+          return waitThenRetry(
+            waitForRetry(
+              events,
+              `flaky ${what} (fresh retry)`,
+              flakyAttempt,
+              options.flakyRetries,
+              error,
+              options.flakyDelay
+            ),
+            () => loop(transientAttempt, flakyAttempt + 1)
+          )
+        }
+
+        if (isTransient(error) && transientAttempt < options.maxRetries) {
+          return waitThenRetry(
+            waitForRetry(
+              events,
+              `transient error (${what})`,
+              transientAttempt,
+              options.maxRetries,
+              error,
+              transientDelay(error, backoff(options.baseDelay, transientAttempt))
+            ),
+            () => loop(transientAttempt + 1, flakyAttempt)
+          )
+        }
+
+        return Stream.fail(error)
+      }
+    )
+
+  return loop(0, 0)
+}
+
+export const makeTransientRetry = Effect.fn("@llm4ts/flow/TransientRetry.make")(function* (
+  underlying: LlmServiceShape,
+  retryOptions: TransientRetryOptions = {}
+): Effect.fn.Return<LlmServiceShape, never, FlowEvents> {
+  const events = yield* FlowEvents
+  const options = resolveOptions(retryOptions)
+
+  return LlmService.of({
+    executeStream: (prompt) =>
+      retryStream(underlying.executeStream(prompt), "stream", options, events),
+    executeStreamWithHistory: (messages) =>
+      retryStream(underlying.executeStreamWithHistory(messages), "stream", options, events),
+    executeWithTools: (prompt, tools) =>
+      retryEffect(underlying.executeWithTools(prompt, tools), "tools", options, events),
+    executeStructured: (prompt, schema, jsonSchema) =>
+      retryEffect(
+        underlying.executeStructured(prompt, schema, jsonSchema),
+        "structured",
+        options,
+        events
+      ),
+    executeStructuredWithUsage: (prompt, schema, jsonSchema) =>
+      retryEffect(
+        underlying.executeStructuredWithUsage(prompt, schema, jsonSchema),
+        "structured",
+        options,
+        events
+      ),
+    isAvailable: underlying.isAvailable
+  })
+})

package/src/Workspace.ts

@@ -0,0 +1,255 @@
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import { WorkspaceIoError, WorkspaceLimitError, WorkspacePathError } from "./FlowError.ts"
+
+export type WorkspaceError = WorkspacePathError | WorkspaceLimitError | WorkspaceIoError
+
+export class SearchMatch extends Schema.Class<SearchMatch>("SearchMatch")({
+  path: Schema.String,
+  line: Schema.Int,
+  text: Schema.String
+}) {}
+
+export interface WorkspaceLimits {
+  readonly maxReadBytes: number
+  readonly maxWriteBytes: number
+  readonly maxResults: number
+  readonly maxDepth: number
+}
+
+export const defaultWorkspaceLimits: WorkspaceLimits = Object.freeze({
+  maxReadBytes: 1_048_576,
+  maxWriteBytes: 1_048_576,
+  maxResults: 1_000,
+  maxDepth: 32
+})
+
+export interface WorkspaceShape {
+  readonly root: string
+  readonly resolve: (path: string) => Effect.Effect<string, WorkspaceError>
+  readonly read: (path: string) => Effect.Effect<string, WorkspaceError>
+  readonly write: (path: string, contents: string) => Effect.Effect<void, WorkspaceError>
+  readonly append: (path: string, contents: string) => Effect.Effect<void, WorkspaceError>
+  readonly discover: (pattern?: string) => Effect.Effect<ReadonlyArray<string>, WorkspaceError>
+  readonly search: (
+    query: string,
+    pattern?: string
+  ) => Effect.Effect<ReadonlyArray<SearchMatch>, WorkspaceError>
+}
+
+export class Workspace extends Context.Service<Workspace, WorkspaceShape>()(
+  "@llm4ts/flow/Workspace"
+) {}
+
+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 comparePaths = (left: string, right: string): number => {
+  const leftSegments = left.split("/")
+  const rightSegments = right.split("/")
+  const shared = Math.min(leftSegments.length, rightSegments.length)
+  for (let index = 0; index < shared; index += 1) {
+    const order = (leftSegments[index] ?? "").localeCompare(rightSegments[index] ?? "")
+    if (order !== 0) {
+      return order
+    }
+  }
+  return leftSegments.length - rightSegments.length
+}
+
+const byteLength = (contents: string): number => new TextEncoder().encode(contents).length
+
+export interface MemoryWorkspaceOptions {
+  readonly root?: string
+  readonly limits?: WorkspaceLimits
+  readonly initial?: Readonly<Record<string, string>>
+}
+
+export const makeMemoryWorkspace = (
+  options: MemoryWorkspaceOptions = {}
+): Effect.Effect<WorkspaceShape> => {
+  const root = (options.root ?? "/workspace").replace(/\/+$/, "")
+  const limits = options.limits ?? defaultWorkspaceLimits
+
+  const relativeKey = (input: string): string | undefined => {
+    const normalized = input.replaceAll("\\", "/")
+    const withoutRoot =
+      normalized === root
+        ? ""
+        : normalized.startsWith(`${root}/`)
+          ? normalized.slice(root.length + 1)
+          : normalized
+    if (withoutRoot.startsWith("/")) {
+      return undefined
+    }
+    const segments: Array<string> = []
+    for (const part of withoutRoot.split("/")) {
+      if (part === "" || part === ".") {
+        continue
+      }
+      if (part === "..") {
+        if (segments.length === 0) {
+          return undefined
+        }
+        segments.pop()
+      } else {
+        segments.push(part)
+      }
+    }
+    return segments.join("/")
+  }
+
+  const resolveKey = (input: string): Effect.Effect<string, WorkspaceError> => {
+    const key = relativeKey(input)
+    return key === undefined
+      ? Effect.fail(
+          WorkspacePathError.make({
+            path: input,
+            message: "path escapes the configured workspace"
+          })
+        )
+      : Effect.succeed(key)
+  }
+
+  return Ref.make<Readonly<Record<string, string>>>(options.initial ?? {}).pipe(
+    Effect.map((state) => {
+      const read = (input: string): Effect.Effect<string, WorkspaceError> =>
+        Effect.gen(function* () {
+          const key = yield* resolveKey(input)
+          const files = yield* Ref.get(state)
+          const contents = files[key]
+          if (contents === undefined) {
+            return yield* WorkspaceIoError.make({
+              operation: "read",
+              path: input,
+              message: "file does not exist"
+            })
+          }
+          const bytes = byteLength(contents)
+          if (bytes > limits.maxReadBytes) {
+            return yield* WorkspaceLimitError.make({
+              operation: "read bytes",
+              limit: limits.maxReadBytes,
+              actual: bytes
+            })
+          }
+          return contents
+        })
+
+      const writeBounded = (
+        operation: "write" | "append",
+        input: string,
+        contents: string
+      ): Effect.Effect<void, WorkspaceError> => {
+        const bytes = byteLength(contents)
+        if (bytes > limits.maxWriteBytes) {
+          return Effect.fail(
+            WorkspaceLimitError.make({
+              operation: `${operation} bytes`,
+              limit: limits.maxWriteBytes,
+              actual: bytes
+            })
+          )
+        }
+        return resolveKey(input).pipe(
+          Effect.flatMap((key) =>
+            Ref.update(state, (files) => ({
+              ...files,
+              [key]: operation === "write" ? contents : `${files[key] ?? ""}${contents}`
+            }))
+          )
+        )
+      }
+
+      const discover = (pattern = "**/*"): Effect.Effect<ReadonlyArray<string>, WorkspaceError> =>
+        Effect.gen(function* () {
+          const normalizedPattern = pattern.replaceAll("\\", "/")
+          const matcher = normalizedPattern === "**/*" ? /.*/ : globRegex(normalizedPattern)
+          const files = yield* Ref.get(state)
+          const results: Array<string> = []
+          for (const path of Object.keys(files).sort(comparePaths)) {
+            const depth = path.split("/").length - 1
+            if (depth > limits.maxDepth) {
+              return yield* WorkspaceLimitError.make({
+                operation: "discovery depth",
+                limit: limits.maxDepth,
+                actual: depth
+              })
+            }
+            if (matcher.test(path)) {
+              results.push(path)
+              if (results.length > limits.maxResults) {
+                return yield* WorkspaceLimitError.make({
+                  operation: "discovery results",
+                  limit: limits.maxResults,
+                  actual: results.length
+                })
+              }
+            }
+          }
+          return results
+        })
+
+      const search = (
+        query: string,
+        pattern = "**/*"
+      ): Effect.Effect<ReadonlyArray<SearchMatch>, WorkspaceError> =>
+        Effect.gen(function* () {
+          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: (input: string) =>
+          resolveKey(input).pipe(Effect.map((key) => (key === "" ? root : `${root}/${key}`))),
+        read,
+        write: (path: string, contents: string) => writeBounded("write", path, contents),
+        append: (path: string, contents: string) => writeBounded("append", path, contents),
+        discover,
+        search
+      }
+    })
+  )
+}

package/src/WorkspaceLayout.ts

@@ -0,0 +1,22 @@
+import { stableHash } from "./Plan.ts"
+
+const normalize = (path: string): string => path.replaceAll("\\", "/").replace(/\/+$/, "")
+
+const basename = (path: string): string => {
+  const parts = normalize(path).split("/")
+  return parts.at(-1) || "repo"
+}
+
+export const repoId = (workspace: string, repository: string): string | undefined => {
+  const normalizedWorkspace = normalize(workspace)
+  const normalizedRepository = normalize(repository)
+  return normalizedWorkspace === normalizedRepository
+    ? undefined
+    : `${basename(normalizedRepository)}-${stableHash(normalizedRepository)}`
+}
+
+export const llm4tsDirectory = (workspace: string, repository: string): string => {
+  const root = `${normalize(workspace)}/.llm4ts`
+  const id = repoId(workspace, repository)
+  return id === undefined ? root : `${root}/${id}`
+}

package/src/WorkspaceTools.ts

@@ -0,0 +1,188 @@
+import * as Effect from "effect/Effect"
+import { ToolExecutionFailed, makeTool, type Tool } from "@llm4ts/core/tools/Tool"
+import { isJsonRecord } from "@llm4ts/core/providers/CliSupport"
+import type { JsonValue } from "@llm4ts/core/providers/CliSupport"
+import type { WorkspaceShape } from "./Workspace.ts"
+
+const parameter = (
+  parameters: JsonValue,
+  name: string
+): Effect.Effect<string, ToolExecutionFailed> => {
+  if (!isJsonRecord(parameters)) {
+    return Effect.fail(
+      ToolExecutionFailed.make({
+        message: "tool parameters must be an object"
+      })
+    )
+  }
+  const value = parameters[name]
+  return typeof value === "string"
+    ? Effect.succeed(value)
+    : Effect.fail(
+        ToolExecutionFailed.make({
+          message: `parameter '${name}' must be a string`
+        })
+      )
+}
+
+const optionalParameter = (
+  parameters: JsonValue,
+  name: string
+): Effect.Effect<string | undefined, ToolExecutionFailed> => {
+  if (!isJsonRecord(parameters)) {
+    return Effect.fail(
+      ToolExecutionFailed.make({
+        message: "tool parameters must be an object"
+      })
+    )
+  }
+  const value = parameters[name]
+  return value === undefined || typeof value === "string"
+    ? Effect.succeed(value)
+    : Effect.fail(
+        ToolExecutionFailed.make({
+          message: `parameter '${name}' must be a string when supplied`
+        })
+      )
+}
+
+const mapWorkspaceError = Effect.mapError((error: { readonly message: string }) =>
+  ToolExecutionFailed.make({ message: error.message })
+)
+
+const pathSchema = {
+  type: "object",
+  properties: {
+    path: { type: "string" }
+  },
+  required: ["path"],
+  additionalProperties: false
+}
+
+const contentSchema = {
+  type: "object",
+  properties: {
+    path: { type: "string" },
+    contents: { type: "string" }
+  },
+  required: ["path", "contents"],
+  additionalProperties: false
+}
+
+export const workspaceTools = (workspace: WorkspaceShape): ReadonlyArray<Tool> => [
+  makeTool({
+    name: "workspace_read",
+    description: "Read a bounded UTF-8 file under the workspace root",
+    parameters: pathSchema,
+    tags: ["file", "read", "workspace"],
+    sandbox: "WorkspaceReadOnly",
+    execute: (parameters) =>
+      Effect.all({
+        path: parameter(parameters, "path")
+      }).pipe(
+        Effect.flatMap(({ path }) => workspace.read(path)),
+        mapWorkspaceError
+      )
+  }),
+  makeTool({
+    name: "workspace_write",
+    description: "Write bounded UTF-8 content under the workspace root",
+    parameters: contentSchema,
+    tags: ["file", "write", "workspace"],
+    execute: (parameters) =>
+      Effect.all({
+        path: parameter(parameters, "path"),
+        contents: parameter(parameters, "contents")
+      }).pipe(
+        Effect.flatMap(({ path, contents }) => workspace.write(path, contents)),
+        mapWorkspaceError,
+        Effect.as({ written: true })
+      )
+  }),
+  makeTool({
+    name: "workspace_append",
+    description: "Append bounded UTF-8 content under the workspace root",
+    parameters: contentSchema,
+    tags: ["file", "append", "workspace"],
+    execute: (parameters) =>
+      Effect.all({
+        path: parameter(parameters, "path"),
+        contents: parameter(parameters, "contents")
+      }).pipe(
+        Effect.flatMap(({ path, contents }) => workspace.append(path, contents)),
+        mapWorkspaceError,
+        Effect.as({ appended: true })
+      )
+  }),
+  makeTool({
+    name: "workspace_discover",
+    description: "Discover files under the workspace root using a bounded glob",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: { type: "string" }
+      },
+      additionalProperties: false
+    },
+    tags: ["file", "glob", "discover", "workspace"],
+    sandbox: "WorkspaceReadOnly",
+    execute: (parameters) =>
+      optionalParameter(parameters, "pattern").pipe(
+        Effect.flatMap((pattern) => workspace.discover(pattern)),
+        mapWorkspaceError,
+        Effect.map((paths) => [...paths])
+      )
+  }),
+  makeTool({
+    name: "workspace_search",
+    description: "Search bounded workspace files for literal text",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        pattern: { type: "string" }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    tags: ["file", "search", "workspace"],
+    sandbox: "WorkspaceReadOnly",
+    execute: (parameters) =>
+      Effect.all({
+        query: parameter(parameters, "query"),
+        pattern: optionalParameter(parameters, "pattern")
+      }).pipe(
+        Effect.flatMap(({ pattern, query }) => workspace.search(query, pattern)),
+        mapWorkspaceError,
+        Effect.map((matches) =>
+          matches.map((match) => ({
+            path: match.path,
+            line: match.line,
+            text: match.text
+          }))
+        )
+      )
+  }),
+  makeTool({
+    name: "workspace_validate_json",
+    description: "Validate that a bounded workspace file contains JSON",
+    parameters: pathSchema,
+    tags: ["file", "validate", "json", "workspace"],
+    sandbox: "WorkspaceReadOnly",
+    execute: (parameters) =>
+      parameter(parameters, "path").pipe(
+        Effect.flatMap((path) => workspace.read(path)),
+        mapWorkspaceError,
+        Effect.flatMap((contents) =>
+          Effect.try({
+            try: () => JSON.parse(contents),
+            catch: (error) =>
+              ToolExecutionFailed.make({
+                message: `invalid JSON: ${String(error)}`
+              })
+          })
+        ),
+        Effect.as({ valid: true })
+      )
+  })
+]