@llm4ts/flow 0.1.0

package/src/Planner.ts

@@ -0,0 +1,134 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import { collect } from "@llm4ts/core/Streaming"
+import { FlowLlmError } from "./FlowError.ts"
+import { Plan } from "./Plan.ts"
+
+export class Proceed extends Schema.Class<Proceed>("Proceed")({
+  kind: Schema.Literal("Proceed"),
+  value: Plan
+}) {}
+
+export class Blocked extends Schema.Class<Blocked>("Blocked")({
+  kind: Schema.Literal("Blocked"),
+  reason: Schema.String
+}) {}
+
+export const Verdict = Schema.Union([Proceed, Blocked])
+export type Verdict = typeof Verdict.Type
+
+export const planJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    epicId: { type: "string" },
+    tasks: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          completed: { type: "boolean" }
+        },
+        required: ["title", "description", "completed"]
+      }
+    },
+    brief: { type: "string" }
+  },
+  required: ["epicId", "tasks"]
+}
+
+const verdictJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    kind: { type: "string", enum: ["Proceed", "Blocked"] },
+    value: planJsonSchema,
+    reason: { type: "string" }
+  },
+  required: ["kind"]
+}
+
+export const defaultPlanInstructions = [
+  "You are a planning assistant. Break the user's request into an ordered list of small,",
+  "independently implementable tasks. Each task must be a thin vertical slice with an observable",
+  "outcome, described in terms of behavior rather than mechanism. Choose a short kebab-case epicId.",
+  'Respond only with JSON: {"epicId":"kebab-case-id","tasks":',
+  '[{"title":"...","description":"...","completed":false}]}'
+].join("\n")
+
+export const planFrom = Effect.fn("@llm4ts/flow/Planner.from")(function* (
+  reasoning: LlmServiceShape,
+  prompt: string,
+  instructions = defaultPlanInstructions
+): Effect.fn.Return<Plan, FlowLlmError> {
+  return yield* reasoning
+    .executeStructured(`${instructions}\n\nRequest:\n${prompt}`, Plan, planJsonSchema)
+    .pipe(Effect.mapError(FlowLlmError.from))
+})
+
+export const reviewPlanInstructions = [
+  "Review the draft implementation plan for correctness, completeness, simplicity, and concision.",
+  "Keep the same epicId unless it is clearly wrong. Return the complete improved plan, not a patch.",
+  'Respond only with JSON: {"epicId":"kebab-case-id","tasks":',
+  '[{"title":"...","description":"...","completed":false}]}'
+].join("\n")
+
+export const reviewPlan = Effect.fn("@llm4ts/flow/Planner.review")(function* (
+  reasoning: LlmServiceShape,
+  plan: Plan,
+  instructions = reviewPlanInstructions
+): Effect.fn.Return<Plan, FlowLlmError> {
+  const improved = yield* reasoning
+    .executeStructured(`${instructions}\n\nDraft plan:\n${plan.render}`, Plan, planJsonSchema)
+    .pipe(Effect.mapError(FlowLlmError.from))
+  return Plan.make({
+    ...improved,
+    ...(plan.brief === undefined ? {} : { brief: plan.brief })
+  })
+})
+
+export const briefInstructions = [
+  "Write a concise codebase brief for an engineer about to implement this change:",
+  "relevant modules and file paths, important APIs and types, conventions, and build/test commands.",
+  "Explore the repository as needed. Do not restate the task list. Return plain prose."
+].join("\n")
+
+export const writeBrief = Effect.fn("@llm4ts/flow/Planner.brief")(function* (
+  reasoning: LlmServiceShape,
+  prompt: string,
+  instructions = briefInstructions
+): Effect.fn.Return<string, FlowLlmError> {
+  const response = yield* collect(
+    reasoning.executeStream(`${instructions}\n\nChange request:\n${prompt}`)
+  ).pipe(Effect.mapError(FlowLlmError.from))
+  return response.content.trim()
+})
+
+export const briefPlan = Effect.fn("@llm4ts/flow/Planner.briefPlan")(function* (
+  reasoning: LlmServiceShape,
+  plan: Plan,
+  prompt: string,
+  instructions = briefInstructions
+): Effect.fn.Return<Plan, FlowLlmError> {
+  const brief = yield* writeBrief(reasoning, prompt, instructions)
+  return Plan.make({ ...plan, brief })
+})
+
+export const assessThenPlanInstructions = [
+  "First decide whether this request is ready to implement.",
+  'Respond only with JSON using exactly one form: {"kind":"Blocked","reason":"why it cannot proceed"}',
+  'or {"kind":"Proceed","value":{"epicId":"kebab-id","tasks":',
+  '[{"title":"...","description":"...","completed":false}]}}.'
+].join("\n")
+
+export const assessThenPlan = Effect.fn("@llm4ts/flow/Planner.assessThenPlan")(function* (
+  reasoning: LlmServiceShape,
+  prompt: string,
+  instructions = assessThenPlanInstructions
+): Effect.fn.Return<Verdict, FlowLlmError> {
+  return yield* reasoning
+    .executeStructured(`${instructions}\n\nRequest:\n${prompt}`, Verdict, verdictJsonSchema)
+    .pipe(Effect.mapError(FlowLlmError.from))
+})

package/src/PrSummary.ts

@@ -0,0 +1,37 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import { FlowLlmError } from "./FlowError.ts"
+
+export class PrSummary extends Schema.Class<PrSummary>("PrSummary")({
+  title: Schema.String,
+  body: Schema.String
+}) {}
+
+export const prSummaryJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    body: { type: "string" }
+  },
+  required: ["title", "body"]
+}
+
+export const summarisePr = Effect.fn("@llm4ts/flow/PrSummary.summarise")(function* (
+  reasoning: LlmServiceShape,
+  diff: string,
+  context?: string
+): Effect.fn.Return<PrSummary, FlowLlmError> {
+  const contextBlock =
+    context === undefined || context.length === 0 ? "" : `\nContext:\n${context}\n`
+  const prompt = [
+    'Summarise this change as a pull request. Respond only with JSON: {"title":"...","body":"..."}.',
+    contextBlock,
+    "Diff:",
+    diff
+  ].join("\n")
+  return yield* reasoning
+    .executeStructured(prompt, PrSummary, prSummaryJsonSchema)
+    .pipe(Effect.mapError(FlowLlmError.from))
+})

package/src/PriceList.ts

@@ -0,0 +1,91 @@
+import type { TokenUsage } from "@llm4ts/core/Models"
+
+export interface ModelRate {
+  readonly prefix: string
+  readonly inputUsdPerMillion: number
+  readonly outputUsdPerMillion: number
+  readonly cachedInputMultiplier: number
+}
+
+export const PricesAsOf = "2026-07"
+
+export const ModelRates: ReadonlyArray<ModelRate> = Object.freeze([
+  {
+    prefix: "claude-fable-5",
+    inputUsdPerMillion: 10,
+    outputUsdPerMillion: 50,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "claude-opus-4",
+    inputUsdPerMillion: 15,
+    outputUsdPerMillion: 75,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "claude-sonnet-4",
+    inputUsdPerMillion: 3,
+    outputUsdPerMillion: 15,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "claude-haiku-4",
+    inputUsdPerMillion: 1,
+    outputUsdPerMillion: 5,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "gemini-2.5-pro",
+    inputUsdPerMillion: 1.25,
+    outputUsdPerMillion: 10,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "gemini-2.5-flash",
+    inputUsdPerMillion: 0.3,
+    outputUsdPerMillion: 2.5,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "gpt-5.5",
+    inputUsdPerMillion: 5,
+    outputUsdPerMillion: 30,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "grok-4.5",
+    inputUsdPerMillion: 2,
+    outputUsdPerMillion: 6,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "grok-4.3",
+    inputUsdPerMillion: 1.25,
+    outputUsdPerMillion: 2.5,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "grok-4.20",
+    inputUsdPerMillion: 1.25,
+    outputUsdPerMillion: 2.5,
+    cachedInputMultiplier: 0.1
+  },
+  {
+    prefix: "grok-build-0.1",
+    inputUsdPerMillion: 1,
+    outputUsdPerMillion: 2,
+    cachedInputMultiplier: 0.1
+  }
+])
+
+export const estimateCostUsd = (model: string, usage: TokenUsage): number | undefined => {
+  const rate = ModelRates.find(({ prefix }) => model.startsWith(prefix))
+  if (rate === undefined) {
+    return undefined
+  }
+  return (
+    (usage.prompt / 1_000_000) * rate.inputUsdPerMillion +
+    (usage.completion / 1_000_000) * rate.outputUsdPerMillion +
+    ((usage.cached ?? 0) / 1_000_000) * rate.inputUsdPerMillion * rate.cachedInputMultiplier
+  )
+}

package/src/Provenance.ts

@@ -0,0 +1,85 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PersistenceError, PlanParseError, type FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export class Provenance extends Schema.Class<Provenance>("Provenance")({
+  schema: Schema.Int,
+  pack: Schema.String,
+  llm4tsVersion: Schema.String,
+  createdAt: Schema.String,
+  approvedBy: Schema.optionalKey(Schema.String),
+  seats: Schema.Record(Schema.String, Schema.String),
+  specs: Schema.Record(Schema.String, Schema.String),
+  gateVerdicts: Schema.Record(Schema.String, Schema.String),
+  equivalenceReport: Schema.optionalKey(Schema.String),
+  fixSpecs: Schema.Array(Schema.String)
+}) {}
+
+const join = (root: string, path: string): string =>
+  `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
+
+export interface ProvenanceStoreShape {
+  readonly write: (path: string, provenance: Provenance) => Effect.Effect<void, FlowError>
+  readonly load: (path: string) => Effect.Effect<Provenance, FlowError>
+  readonly extend: (
+    path: string,
+    update: (current: Provenance) => Provenance
+  ) => Effect.Effect<Provenance, FlowError>
+  readonly hashFiles: (
+    root: string,
+    paths: ReadonlyArray<string>
+  ) => Effect.Effect<Readonly<Record<string, string>>, PersistenceError>
+}
+
+export const makeProvenanceStore = (files: PlainFileStoreShape): ProvenanceStoreShape => {
+  const write = (path: string, provenance: Provenance): Effect.Effect<void, FlowError> =>
+    Schema.encodeEffect(Schema.fromJsonString(Provenance))(provenance).pipe(
+      Effect.mapError((error) =>
+        PlanParseError.make({
+          message: `failed to encode provenance manifest ${path}: ${String(error)}`
+        })
+      ),
+      Effect.flatMap((contents) => files.writeAtomic(path, `${contents}\n`))
+    )
+
+  const load = (path: string): Effect.Effect<Provenance, FlowError> =>
+    Effect.flatMap(
+      files.read(path),
+      (contents): Effect.Effect<Provenance, FlowError> =>
+        contents === undefined
+          ? Effect.fail(
+              PersistenceError.make({
+                message: `provenance manifest does not exist: ${path}`
+              })
+            )
+          : Schema.decodeUnknownEffect(Schema.fromJsonString(Provenance))(contents).pipe(
+              Effect.mapError((error) =>
+                PlanParseError.make({
+                  message: `malformed provenance manifest ${path}: ${String(error)}`
+                })
+              )
+            )
+    )
+
+  const extend = (
+    path: string,
+    update: (current: Provenance) => Provenance
+  ): Effect.Effect<Provenance, FlowError> =>
+    Effect.flatMap(load(path), (current) => {
+      const updated = update(current)
+      return write(path, updated).pipe(Effect.as(updated))
+    })
+
+  const hashFiles = (
+    root: string,
+    paths: ReadonlyArray<string>
+  ): Effect.Effect<Readonly<Record<string, string>>, PersistenceError> =>
+    Effect.forEach(paths, (path) =>
+      files
+        .hashSha256(join(root, path))
+        .pipe(Effect.map((hash): readonly [path: string, hash: string] => [path, hash]))
+    ).pipe(Effect.map(Object.fromEntries))
+
+  return { write, load, extend, hashFiles }
+}

package/src/Replay.ts

@@ -0,0 +1,265 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import { InvalidRequestError, ParseError, ProviderError } from "@llm4ts/core/Errors"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import { LlmChunk, TokenUsage } from "@llm4ts/core/Models"
+import { collect } from "@llm4ts/core/Streaming"
+import { PlanParseError, UnsupportedSchemaVersion, type FlowError } from "./FlowError.ts"
+import { TraceLine } from "./FlowRecorder.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export const CurrentTraceSchema = 1
+
+export class ReplaySuccess extends Schema.TaggedClass<ReplaySuccess>()("Success", {
+  text: Schema.String,
+  usage: Schema.optionalKey(TokenUsage),
+  model: Schema.optionalKey(Schema.String)
+}) {}
+
+export class ReplayFailure extends Schema.TaggedClass<ReplayFailure>()("Failure", {
+  message: Schema.String,
+  model: Schema.optionalKey(Schema.String)
+}) {}
+
+export const ReplayTurn = Schema.Union([ReplaySuccess, ReplayFailure])
+export type ReplayTurn = typeof ReplayTurn.Type
+
+const stringField = (
+  fields: Readonly<Record<string, unknown>>,
+  key: string
+): string | undefined => {
+  const value = fields[key]
+  return typeof value === "string" ? value : undefined
+}
+
+const integerField = (
+  fields: Readonly<Record<string, unknown>>,
+  key: string
+): number | undefined => {
+  const value = stringField(fields, key)
+  if (value === undefined || !/^-?\d+$/.test(value)) {
+    return undefined
+  }
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+const isSafeInteger = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value)
+
+const flowEventFields = (line: TraceLine): Readonly<Record<string, unknown>> => {
+  const event = line.fields.event
+  if (typeof event !== "string") {
+    return line.fields
+  }
+  try {
+    const decoded: unknown = JSON.parse(event)
+    if (typeof decoded !== "object" || decoded === null) {
+      return line.fields
+    }
+    return Object.fromEntries(
+      Object.keys(decoded).map((key): readonly [string, unknown] => [
+        key,
+        Reflect.get(decoded, key)
+      ])
+    )
+  } catch {
+    return line.fields
+  }
+}
+
+export const segmentReplayTurns = (lines: ReadonlyArray<TraceLine>): ReadonlyArray<ReplayTurn> => {
+  let pendingUsage: TokenUsage | undefined
+  let pendingModel: string | undefined
+  const turns: Array<ReplayTurn> = []
+
+  for (const line of [...lines].sort((left, right) => left.seq - right.seq)) {
+    const fields = flowEventFields(line)
+    switch (line.kind) {
+      case "TokensUsed": {
+        const usageValue =
+          typeof fields.usage === "object" && fields.usage !== null
+            ? {
+                prompt: Reflect.get(fields.usage, "prompt"),
+                completion: Reflect.get(fields.usage, "completion"),
+                total: Reflect.get(fields.usage, "total"),
+                cached: Reflect.get(fields.usage, "cached")
+              }
+            : fields
+        const prompt =
+          typeof usageValue.prompt === "number" ? usageValue.prompt : integerField(fields, "prompt")
+        const completion =
+          typeof usageValue.completion === "number"
+            ? usageValue.completion
+            : integerField(fields, "completion")
+        const total =
+          typeof usageValue.total === "number" ? usageValue.total : integerField(fields, "total")
+        const cached = typeof usageValue.cached === "number" ? usageValue.cached : undefined
+        if (isSafeInteger(prompt) && isSafeInteger(completion) && isSafeInteger(total)) {
+          pendingUsage = TokenUsage.make({
+            prompt,
+            completion,
+            total,
+            ...(cached === undefined ? {} : { cached })
+          })
+        }
+        pendingModel = stringField(fields, "model") ?? pendingModel
+        break
+      }
+      case "AssistantMessage":
+        turns.push(
+          ReplaySuccess.make({
+            text: stringField(fields, "text") ?? "",
+            ...(pendingUsage === undefined ? {} : { usage: pendingUsage }),
+            ...(pendingModel === undefined ? {} : { model: pendingModel })
+          })
+        )
+        pendingUsage = undefined
+        pendingModel = undefined
+        break
+      case "StreamError": {
+        const model = stringField(fields, "model")
+        turns.push(
+          ReplayFailure.make({
+            message: stringField(fields, "message") ?? "",
+            ...(model === undefined ? {} : { model })
+          })
+        )
+        pendingUsage = undefined
+        pendingModel = undefined
+        break
+      }
+    }
+  }
+  return turns
+}
+
+const traceCodec = Schema.fromJsonString(TraceLine)
+
+export const readTrace = Effect.fn("@llm4ts/flow/Replay.readTrace")(function* (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.fn.Return<ReadonlyArray<TraceLine>, FlowError> {
+  const contents = yield* files.read(path)
+  if (contents === undefined) {
+    return yield* PlanParseError.make({
+      message: `trace does not exist: ${path}`
+    })
+  }
+  const lines = contents
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+  const decoded = yield* Effect.forEach(
+    lines,
+    (line, index) =>
+      Schema.decodeUnknownEffect(traceCodec)(line).pipe(
+        Effect.mapError((error) =>
+          PlanParseError.make({
+            message: `malformed trace at ${path}:${index + 1}: ${String(error)}`
+          })
+        )
+      ),
+    { concurrency: 1 }
+  )
+  for (const line of decoded) {
+    const actual = line.schemaVersion ?? 1
+    if (actual !== CurrentTraceSchema) {
+      return yield* UnsupportedSchemaVersion.make({
+        path,
+        expected: CurrentTraceSchema,
+        actual
+      })
+    }
+  }
+  return [...decoded].sort((left, right) => left.seq - right.seq)
+})
+
+export const makeReplayConnector = Effect.fn("@llm4ts/flow/Replay.makeConnector")(function* (
+  turns: ReadonlyArray<ReplayTurn>
+): Effect.fn.Return<LlmServiceShape> {
+  const cursor = yield* Ref.make(0)
+
+  const next = Stream.unwrap(
+    Ref.getAndUpdate(cursor, (index) => index + 1).pipe(
+      Effect.map((index) => {
+        const turn = turns[index]
+        if (turn === undefined) {
+          return Stream.fail(
+            ProviderError.make({
+              message: `replay trace exhausted at turn ${index}`
+            })
+          )
+        }
+        if (turn._tag === "Failure") {
+          return Stream.fail(ProviderError.make({ message: turn.message }))
+        }
+        return Stream.succeed(
+          LlmChunk.make({
+            delta: turn.text,
+            finishReason: "stop",
+            ...(turn.usage === undefined ? {} : { usage: turn.usage }),
+            metadata: {
+              provider: "replay",
+              ...(turn.model === undefined ? {} : { model: turn.model })
+            }
+          })
+        )
+      })
+    )
+  )
+
+  return {
+    executeStream: (_prompt) => next,
+    executeStreamWithHistory: (_messages) => next,
+    executeWithTools: (_prompt, _tools) =>
+      Effect.fail(
+        InvalidRequestError.make({
+          message: "replay does not support tool calling"
+        })
+      ),
+    executeStructured: <A, E, RD, RE>(
+      _prompt: string,
+      schema: Schema.ConstraintCodec<A, E, RD, RE>
+    ) =>
+      collect(next).pipe(
+        Effect.flatMap((response) =>
+          Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(response.content)
+        ),
+        Effect.mapError((error) =>
+          ParseError.make({
+            message: `replay structured parse error: ${String(error)}`,
+            raw: error instanceof ParseError ? error.raw : ""
+          })
+        )
+      ),
+    executeStructuredWithUsage: <A, E, RD, RE>(
+      _prompt: string,
+      schema: Schema.ConstraintCodec<A, E, RD, RE>
+    ) =>
+      collect(next).pipe(
+        Effect.flatMap((response) =>
+          Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(response.content).pipe(
+            Effect.map((value) => [value, response.usage, response.metadata.model] as const)
+          )
+        ),
+        Effect.mapError((error) =>
+          ParseError.make({
+            message: `replay structured parse error: ${String(error)}`,
+            raw: ""
+          })
+        )
+      ),
+    isAvailable: Effect.succeed(true)
+  }
+})
+
+export const replayFromTrace = Effect.fn("@llm4ts/flow/Replay.fromTrace")(function* (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.fn.Return<LlmServiceShape, FlowError> {
+  const lines = yield* readTrace(files, path)
+  return yield* makeReplayConnector(segmentReplayTurns(lines))
+})