@llm4ts/flow 0.1.0

package/src/FlowEvents.ts

@@ -0,0 +1,147 @@
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as PubSub from "effect/PubSub"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { TokenUsage } from "@llm4ts/core/Models"
+
+export class StageStarted extends Schema.TaggedClass<StageStarted>()("StageStarted", {
+  stage: Schema.String
+}) {}
+
+export class StageCompleted extends Schema.TaggedClass<StageCompleted>()("StageCompleted", {
+  stage: Schema.String
+}) {}
+
+export class StageFailed extends Schema.TaggedClass<StageFailed>()("StageFailed", {
+  stage: Schema.String,
+  message: Schema.String
+}) {}
+
+export class Aborted extends Schema.TaggedClass<Aborted>()("Aborted", {
+  message: Schema.String
+}) {}
+
+export class Info extends Schema.TaggedClass<Info>()("Info", {
+  message: Schema.String
+}) {}
+
+export class ToolUse extends Schema.TaggedClass<ToolUse>()("ToolUse", {
+  tool: Schema.String,
+  args: Schema.String
+}) {}
+
+export class AssistantMessage extends Schema.TaggedClass<AssistantMessage>()("AssistantMessage", {
+  text: Schema.String
+}) {}
+
+export class TokensUsed extends Schema.TaggedClass<TokensUsed>()("TokensUsed", {
+  agent: Schema.String,
+  model: Schema.optionalKey(Schema.String),
+  usage: TokenUsage
+}) {}
+
+export class CapabilityUsedEvent extends Schema.TaggedClass<CapabilityUsedEvent>()(
+  "CapabilityUsed",
+  {
+    capability: Schema.String,
+    operation: Schema.String
+  }
+) {}
+
+export class CapabilityDeniedEvent extends Schema.TaggedClass<CapabilityDeniedEvent>()(
+  "CapabilityDenied",
+  {
+    capability: Schema.String,
+    operation: Schema.String
+  }
+) {}
+
+export class CapabilityUnenforceable extends Schema.TaggedClass<CapabilityUnenforceable>()(
+  "CapabilityUnenforceable",
+  {
+    detail: Schema.String
+  }
+) {}
+
+export class Declassified extends Schema.TaggedClass<Declassified>()("Declassified", {
+  label: Schema.String
+}) {}
+
+export const FlowEvent = Schema.Union([
+  StageStarted,
+  StageCompleted,
+  StageFailed,
+  Aborted,
+  Info,
+  ToolUse,
+  AssistantMessage,
+  TokensUsed,
+  CapabilityUsedEvent,
+  CapabilityDeniedEvent,
+  CapabilityUnenforceable,
+  Declassified
+])
+export type FlowEvent = typeof FlowEvent.Type
+
+export const FlowEventsValues = Object.freeze({
+  CapabilityUsed: (capability: string, operation: string): CapabilityUsedEvent =>
+    new CapabilityUsedEvent({ capability, operation }),
+  CapabilityDenied: (capability: string, operation: string): CapabilityDeniedEvent =>
+    new CapabilityDeniedEvent({ capability, operation }),
+  CapabilityUnenforceable: (detail: string): CapabilityUnenforceable =>
+    new CapabilityUnenforceable({ detail }),
+  Declassified: (label: string): Declassified => new Declassified({ label })
+})
+
+export interface FlowEventsShape {
+  readonly publish: (event: FlowEvent) => Effect.Effect<void>
+}
+
+export class FlowEvents extends Context.Service<FlowEvents, FlowEventsShape>()(
+  "@llm4ts/flow/FlowEvents"
+) {}
+
+const noopFlowEvents = FlowEvents.of({
+  publish: (_event) => Effect.void
+})
+
+export const FlowEventsNoop = Layer.succeed(FlowEvents)(noopFlowEvents)
+
+export interface CollectingFlowEvents extends FlowEventsShape {
+  readonly recorded: Effect.Effect<ReadonlyArray<FlowEvent>>
+}
+
+export const makeCollectingFlowEvents: Effect.Effect<CollectingFlowEvents> = Effect.map(
+  Ref.make<ReadonlyArray<FlowEvent>>([]),
+  (events) => ({
+    publish: (event) => Ref.update(events, (recorded) => [...recorded, event]),
+    recorded: Ref.get(events)
+  })
+)
+
+export interface FlowEventHub extends FlowEventsShape {
+  readonly subscribe: Effect.Effect<PubSub.Subscription<FlowEvent>, never, Scope.Scope>
+  readonly stream: Stream.Stream<FlowEvent>
+  readonly publishedCount: Effect.Effect<number>
+}
+
+export const makeFlowEventHub = Effect.fn("@llm4ts/flow/FlowEvents.makeHub")(function* (
+  capacity = 64
+): Effect.fn.Return<FlowEventHub> {
+  const events = yield* PubSub.bounded<FlowEvent>(capacity)
+  const published = yield* Ref.make(0)
+  return {
+    publish: (event) =>
+      Ref.update(published, (count) => count + 1).pipe(
+        Effect.andThen(PubSub.publish(events, event)),
+        Effect.asVoid
+      ),
+    subscribe: PubSub.subscribe(events),
+    stream: Stream.fromPubSub(events),
+    publishedCount: Ref.get(published)
+  }
+})

package/src/FlowRecorder.ts

@@ -0,0 +1,116 @@
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import * as Semaphore from "effect/Semaphore"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import type { StreamRecorder } from "@llm4ts/core/observability/StreamRecorder"
+import type { JsonValue } from "@llm4ts/core/providers/CliSupport"
+import type { FlowEvent, FlowEventHub } from "./FlowEvents.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export class TraceLine extends Schema.Class<TraceLine>("TraceLine")({
+  schemaVersion: Schema.optionalKey(Schema.Int),
+  seq: Schema.Int,
+  timestamp: Schema.Number,
+  runId: Schema.String,
+  kind: Schema.String,
+  fields: Schema.Record(Schema.String, Schema.Json)
+}) {}
+
+export interface FlowRecorderShape extends StreamRecorder {
+  readonly runId: string
+  readonly tracePath: string
+  readonly record: (event: FlowEvent) => Effect.Effect<void>
+  readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
+  readonly awaitDrained: (hub: FlowEventHub) => Effect.Effect<void>
+}
+
+const encode = (line: TraceLine): string =>
+  JSON.stringify({
+    schemaVersion: line.schemaVersion,
+    seq: line.seq,
+    timestamp: line.timestamp,
+    runId: line.runId,
+    kind: line.kind,
+    fields: line.fields
+  })
+
+export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(function* (
+  files: PlainFileStoreShape,
+  tracePath: string,
+  runId: string
+): Effect.fn.Return<FlowRecorderShape> {
+  const sequence = yield* Ref.make(0)
+  const consumed = yield* Ref.make(0)
+  const lock = yield* Semaphore.make(1)
+  const degraded = yield* Ref.make(false)
+
+  const append = (kind: string, fields: Readonly<Record<string, JsonValue>>): Effect.Effect<void> =>
+    lock.withPermit(
+      Effect.gen(function* () {
+        if (yield* Ref.get(degraded)) {
+          return
+        }
+        const seq = yield* Ref.getAndUpdate(sequence, (current) => current + 1)
+        const timestamp = yield* Clock.currentTimeMillis
+        const line = TraceLine.make({
+          schemaVersion: 1,
+          seq,
+          timestamp,
+          runId,
+          kind,
+          fields
+        })
+        yield* files
+          .append(tracePath, `${encode(line)}\n`)
+          .pipe(Effect.catch(() => Ref.set(degraded, true)))
+      })
+    )
+
+  const record = (event: FlowEvent): Effect.Effect<void> =>
+    append(event._tag, { event: JSON.stringify(event) })
+
+  const recorder: FlowRecorderShape = {
+    runId,
+    tracePath,
+    record,
+    rawLine: (provider, model, line) =>
+      append("RawLine", {
+        provider,
+        ...(model === undefined ? {} : { model }),
+        line
+      }),
+    streamError: (provider, model, message) =>
+      append("StreamError", {
+        provider,
+        ...(model === undefined ? {} : { model }),
+        message
+      }),
+    consume: (hub) =>
+      Effect.gen(function* () {
+        const subscription = yield* hub.subscribe
+        yield* Stream.fromSubscription(subscription).pipe(
+          Stream.runForEach((event) =>
+            record(event).pipe(Effect.andThen(Ref.update(consumed, (count) => count + 1)))
+          ),
+          Effect.forkScoped,
+          Effect.asVoid
+        )
+      }),
+    awaitDrained: (hub) =>
+      Effect.gen(function* () {
+        const target = yield* hub.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* drain
+      })
+  }
+  return recorder
+})

package/src/GitHubTool.ts

@@ -0,0 +1,315 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { Capabilities } from "@llm4ts/core/Capability"
+import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
+import { ProcessError, type FlowError } from "./FlowError.ts"
+import type { FlowEventsShape } from "./FlowEvents.ts"
+import { guarded } from "./CapabilityGuard.ts"
+
+export class IssueRef extends Schema.Class<IssueRef>("IssueRef")({
+  owner: Schema.String,
+  repo: Schema.String,
+  number: Schema.Int
+}) {
+  get shortRef(): string {
+    return `${this.owner}/${this.repo}#${this.number}`
+  }
+}
+
+export const parseIssueRef = (input: string): IssueRef | undefined => {
+  const match = /^([^/\s]+)\/([^#\s]+)#(\d+)$/.exec(input.trim())
+  const owner = match?.[1]
+  const repo = match?.[2]
+  const number = Number.parseInt(match?.[3] ?? "", 10)
+  return owner === undefined || repo === undefined || !Number.isInteger(number) || number <= 0
+    ? undefined
+    : IssueRef.make({ owner, repo, number })
+}
+
+export class Issue extends Schema.Class<Issue>("Issue")({
+  title: Schema.String,
+  body: Schema.String,
+  author: Schema.String
+}) {}
+
+export class PullRequest extends Schema.Class<PullRequest>("PullRequest")({
+  owner: Schema.String,
+  repo: Schema.String,
+  number: Schema.Int,
+  url: Schema.String
+}) {
+  get shortRef(): string {
+    return `${this.owner}/${this.repo}#${this.number}`
+  }
+}
+
+export const BuildOutcome = Schema.Literals(["Success", "Failure", "Pending", "TimedOut"])
+export type BuildOutcome = typeof BuildOutcome.Type
+
+export const parsePullRequestUrl = (url: string): PullRequest | undefined => {
+  const match = /^https?:\/\/[^/]+\/([^/]+)\/([^/]+)\/pull\/(\d+).*$/.exec(url.trim())
+  const owner = match?.[1]
+  const repo = match?.[2]
+  const number = Number.parseInt(match?.[3] ?? "", 10)
+  return owner === undefined || repo === undefined || !Number.isInteger(number)
+    ? undefined
+    : PullRequest.make({
+        owner,
+        repo,
+        number,
+        url: url.trim()
+      })
+}
+
+export const prViewArgs = ["pr", "view", "--json", "url", "--jq", ".url"]
+
+export const prCreateArgs = (
+  title: string,
+  body: string,
+  base: string | undefined,
+  draft: boolean
+): ReadonlyArray<string> => [
+  "pr",
+  "create",
+  "--title",
+  title,
+  "--body",
+  body,
+  ...(base === undefined ? [] : ["--base", base]),
+  ...(draft ? ["--draft"] : [])
+]
+
+export const issueViewArgs = (ref: IssueRef): ReadonlyArray<string> => [
+  "issue",
+  "view",
+  String(ref.number),
+  "--repo",
+  `${ref.owner}/${ref.repo}`,
+  "--json",
+  "title,body,author"
+]
+
+export const issueCommentArgs = (ref: IssueRef, body: string): ReadonlyArray<string> => [
+  "issue",
+  "comment",
+  String(ref.number),
+  "--repo",
+  `${ref.owner}/${ref.repo}`,
+  "--body",
+  body
+]
+
+export const prCommentArgs = (pr: PullRequest, body: string): ReadonlyArray<string> => [
+  "pr",
+  "comment",
+  String(pr.number),
+  "--repo",
+  `${pr.owner}/${pr.repo}`,
+  "--body",
+  body
+]
+
+export const prPatchArgs = (
+  pr: PullRequest,
+  title: string,
+  body: string
+): ReadonlyArray<string> => [
+  "api",
+  "--method",
+  "PATCH",
+  `repos/${pr.owner}/${pr.repo}/pulls/${pr.number}`,
+  "-f",
+  `title=${title}`,
+  "-f",
+  `body=${body}`
+]
+
+export const prChecksArgs = (pr: PullRequest): ReadonlyArray<string> => [
+  "pr",
+  "view",
+  String(pr.number),
+  "--repo",
+  `${pr.owner}/${pr.repo}`,
+  "--json",
+  "statusCheckRollup"
+]
+
+class GhAuthor extends Schema.Class<GhAuthor>("GhAuthor")({
+  login: Schema.String
+}) {}
+
+class GhIssue extends Schema.Class<GhIssue>("GhIssue")({
+  title: Schema.String,
+  body: Schema.String,
+  author: GhAuthor
+}) {}
+
+class GhCheck extends Schema.Class<GhCheck>("GhCheck")({
+  status: Schema.optionalKey(Schema.String),
+  conclusion: Schema.optionalKey(Schema.String),
+  state: Schema.optionalKey(Schema.String)
+}) {}
+
+class GhChecks extends Schema.Class<GhChecks>("GhChecks")({
+  statusCheckRollup: Schema.Array(GhCheck).pipe(
+    Schema.withConstructorDefault(Effect.succeed(Object.freeze([])))
+  )
+}) {}
+
+export const parseIssue = (json: string): Effect.Effect<Issue, ProcessError> =>
+  Schema.decodeUnknownEffect(Schema.fromJsonString(GhIssue))(json).pipe(
+    Effect.map(
+      (issue) =>
+        new Issue({
+          title: issue.title,
+          body: issue.body,
+          author: issue.author.login
+        })
+    ),
+    Effect.mapError((error) =>
+      ProcessError.make({
+        message: "gh issue view",
+        detail: `invalid issue JSON: ${String(error)}`
+      })
+    )
+  )
+
+export const outcomeFromChecksJson = (json: string): Effect.Effect<BuildOutcome, ProcessError> =>
+  Schema.decodeUnknownEffect(Schema.fromJsonString(GhChecks))(json).pipe(
+    Effect.map((parsed) => {
+      const pending = parsed.statusCheckRollup.some(
+        (check) =>
+          (check.status !== undefined && check.status.toUpperCase() !== "COMPLETED") ||
+          ["PENDING", "EXPECTED"].includes(check.state?.toUpperCase() ?? "")
+      )
+      const failed = parsed.statusCheckRollup.some(
+        (check) =>
+          ["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(
+            check.conclusion?.toUpperCase() ?? ""
+          ) || ["FAILURE", "ERROR"].includes(check.state?.toUpperCase() ?? "")
+      )
+      return pending ? "Pending" : failed ? "Failure" : "Success"
+    }),
+    Effect.mapError((error) =>
+      ProcessError.make({
+        message: "gh pr checks",
+        detail: `invalid checks JSON: ${String(error)}`
+      })
+    )
+  )
+
+export interface GitHubToolShape {
+  readonly createPr: (
+    title: string,
+    body: string,
+    base?: string,
+    draft?: boolean
+  ) => Effect.Effect<PullRequest, FlowError>
+  readonly readIssue: (ref: IssueRef) => Effect.Effect<Issue, FlowError>
+  readonly writeIssueComment: (ref: IssueRef, body: string) => Effect.Effect<void, FlowError>
+  readonly writePrComment: (pr: PullRequest, body: string) => Effect.Effect<void, FlowError>
+  readonly updatePr: (
+    pr: PullRequest,
+    title: string,
+    body: string
+  ) => Effect.Effect<void, FlowError>
+  readonly prChecks: (pr: PullRequest) => Effect.Effect<BuildOutcome, FlowError>
+}
+
+const output = (result: ProcessResult): string => result.stdout.join("\n").trim()
+
+export const makeGitHubTool = (
+  process: ProcessExecutorShape,
+  workDir: string,
+  events: FlowEventsShape
+): GitHubToolShape => {
+  const run = (
+    args: ReadonlyArray<string>,
+    allowFailure = false
+  ): Effect.Effect<ProcessResult, FlowError> =>
+    process.run(["gh", ...args], workDir, {}).pipe(
+      Effect.mapError((error) =>
+        ProcessError.make({
+          message: `gh ${args.join(" ")}`,
+          detail: error.message
+        })
+      ),
+      Effect.flatMap((result) =>
+        result.exitCode === 0 || allowFailure
+          ? Effect.succeed(result)
+          : Effect.fail(
+              ProcessError.make({
+                message: `gh ${args.join(" ")}`,
+                detail:
+                  [...result.stdout, ...result.stderr].join("\n").trim() ||
+                  `exit code ${result.exitCode}`
+              })
+            )
+      )
+    )
+
+  const read = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => guarded(Capabilities.GhRead, operation, events, effect)
+  const write = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => guarded(Capabilities.GhWrite, operation, events, effect)
+
+  const findOpenPr = run(prViewArgs, true).pipe(
+    Effect.map((result) =>
+      result.exitCode === 0
+        ? output(result)
+            .split(/\r?\n/)
+            .map(parsePullRequestUrl)
+            .find((item) => item !== undefined)
+        : undefined
+    )
+  )
+
+  return {
+    createPr: (title, body, base, draft = false) =>
+      write(
+        "gh pr create",
+        Effect.flatMap(findOpenPr, (existing) =>
+          existing === undefined
+            ? run(prCreateArgs(title, body, base, draft)).pipe(
+                Effect.flatMap((result) => {
+                  const pr = output(result)
+                    .split(/\r?\n/)
+                    .map(parsePullRequestUrl)
+                    .find((item) => item !== undefined)
+                  return pr === undefined
+                    ? Effect.fail(
+                        ProcessError.make({
+                          message: "gh pr create",
+                          detail: `could not parse a PR URL from: ${output(result)}`
+                        })
+                      )
+                    : Effect.succeed(pr)
+                })
+              )
+            : Effect.succeed(existing)
+        )
+      ),
+    readIssue: (ref) =>
+      read(
+        "gh issue view",
+        run(issueViewArgs(ref)).pipe(Effect.flatMap((result) => parseIssue(output(result))))
+      ),
+    writeIssueComment: (ref, body) =>
+      write("gh issue comment", run(issueCommentArgs(ref, body)).pipe(Effect.asVoid)),
+    writePrComment: (pr, body) =>
+      write("gh pr comment", run(prCommentArgs(pr, body)).pipe(Effect.asVoid)),
+    updatePr: (pr, title, body) =>
+      write("gh pr edit", run(prPatchArgs(pr, title, body)).pipe(Effect.asVoid)),
+    prChecks: (pr) =>
+      read(
+        "gh pr checks",
+        run(prChecksArgs(pr)).pipe(
+          Effect.flatMap((result) => outcomeFromChecksJson(output(result)))
+        )
+      )
+  }
+}