@llm4ts/flow 2.22.2 → 2.24.0

package/src/GitTool.ts

@@ -40,6 +40,10 @@ export interface GitToolShape {
     paths: ReadonlyArray<string>,
     threeDot?: boolean
   ) => Effect.Effect<string, FlowError>
+  /** Tracked files under `paths` (`git ls-files`), relative to the repository. */
+  readonly listFiles: (
+    paths: ReadonlyArray<string>
+  ) => Effect.Effect<ReadonlyArray<string>, FlowError>
   readonly changedFilesVsBase: (
     base: string,
     threeDot?: boolean
@@ -352,6 +356,20 @@ export const makeGitTool = (
             : runOrFail(["diff", `${base}${threeDot ? "..." : ".."}HEAD`, "--", ...paths])
         )
       ),
+    listFiles: (paths) =>
+      read(
+        "git ls-files",
+        Effect.suspend(() =>
+          paths.length === 0 ? Effect.succeed("") : runOrFail(["ls-files", "--", ...paths])
+        )
+      ).pipe(
+        Effect.map((output) =>
+          output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+        )
+      ),
     changedFilesVsBase: (base, threeDot = true) =>
       read(
         "git changedFilesVsBase",

package/src/Stories.ts

@@ -14,6 +14,7 @@ import type * as Scope from "effect/Scope"
 import * as Semaphore from "effect/Semaphore"
 import * as Stream from "effect/Stream"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import { cap } from "./Context.ts"
 import type { LlmChunk, TokenUsage } from "@llm4ts/core/Models"
 import type { LlmError } from "@llm4ts/core/Errors"
 import { BoardItem, type BoardSyncShape } from "./BoardSync.ts"
@@ -294,6 +295,71 @@ export const perimeterRules = (story: Story, where?: StoryWhereabouts): string =
     "- Everything you provide must be implemented completely: other stories depend on it."
   ].join("\n")
 
+/**
+ * The gates run after every task (typecheck, lint, tests, perimeter), so a
+ * coder that runs them itself spends minutes on work the flow repeats.
+ */
+export const gateRules = [
+  "After each task the flow runs the project's gates on your worktree (typecheck, lint, the",
+  "tests) and hands any failure back to you as a finding. Do not run the full test suite,",
+  "typecheck or lint yourself. If you need to check your work, run only the one test file",
+  "that covers your change."
+].join("\n")
+
+const defaultContextChars = 40_000
+const fileChars = 8_000
+
+/**
+ * The code a story starts from, for its coder's system prompt: the shared
+ * read-only files it builds on, then the files it owns, each capped, until
+ * `budget` runs out; the rest by path only. Reading them up front saves the
+ * `ls`/`find`/`cat` round trips the coder would otherwise spend on them.
+ */
+export const startingCodeOf = (
+  story: Story,
+  git: GitToolShape,
+  files: PlainFileStoreShape,
+  worktree: string,
+  budget: number
+): Effect.Effect<string | undefined, FlowError> =>
+  Effect.gen(function* () {
+    if (budget <= 0) {
+      return undefined
+    }
+    const shared = yield* git.listFiles(story.sharedReadOnly)
+    const owned = yield* git.listFiles(story.owned)
+    if (shared.length + owned.length === 0) {
+      return undefined
+    }
+    let left = budget
+    const leftOut: Array<string> = []
+    const section = (title: string, paths: ReadonlyArray<string>) =>
+      Effect.gen(function* () {
+        const parts: Array<string> = []
+        for (const path of paths) {
+          const text = yield* Effect.orElseSucceed(
+            files.read(join(worktree, path)),
+            () => undefined
+          )
+          if (text === undefined || left <= 0) {
+            leftOut.push(path)
+            continue
+          }
+          const shown = cap(text, Math.min(fileChars, left)).text
+          left -= shown.length
+          parts.push(`### ${path}\n\`\`\`\n${shown}\n\`\`\``)
+        }
+        return parts.length === 0 ? [] : [title, ...parts]
+      })
+    return [
+      "## The code you start from",
+      "Read this before exploring: it is the current content of the files below.",
+      ...(yield* section("Shared, read-only — use these as they are:", shared)),
+      ...(yield* section("Yours — the story's owned files so far:", owned)),
+      ...(leftOut.length === 0 ? [] : [`Not shown (over the budget): ${leftOut.join(", ")}`])
+    ].join("\n\n")
+  })
+
 export const storyPrompt = (story: Story): string =>
   [`Story: ${story.title}`, "", story.description.trim()].join("\n")
 
@@ -507,6 +573,13 @@ export interface StoriesOptions {
    * story's plan (coder, review, gates, commit). Default 2: one revision.
    */
   readonly judgeRounds?: number
+  /**
+   * How much of the code a story starts from goes into its coder's system
+   * prompt, in characters: the shared read-only files it uses, then its own.
+   * Each file read up front is a model round trip the coder does not spend
+   * exploring. Default 40 000; 0 leaves it out.
+   */
+  readonly contextChars?: number
   /** Extra system context per story (house rules, shared read-only excerpts). */
   readonly system?: (story: Story) => Effect.Effect<string, FlowError>
   /** How a story's task plan is produced. Default: the story's own coder plans it. */
@@ -828,6 +901,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const extra = options.system === undefined ? undefined : yield* options.system(story)
     const system = [
       perimeterRules(story, { plan, worktree: state.worktree, epicCheckout: context.workDir }),
+      gateRules,
       extra
     ]
       .filter((part): part is string => part !== undefined && part.trim().length > 0)
@@ -995,6 +1069,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     })
 
     const planTasks = options.planTasks ?? defaultPlanTasks
+    // Taken after catch-up and setup: the code as the first task finds it.
+    const startingCode = yield* startingCodeOf(
+      story,
+      git,
+      files,
+      state.worktree,
+      options.contextChars ?? defaultContextChars
+    )
+    const taskSystem = [system, startingCode]
+      .filter((part): part is string => part !== undefined)
+      .join("\n\n")
     const implementTasks = implementPlanFlow(storyContext, {
       store: makePlanStore(files),
       planPath: planPath(story),
@@ -1005,7 +1090,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         prompt,
         laneOf(story)
       ),
-      system,
+      system: taskSystem,
       chatPerTask: true,
       checkoutBranch: false,
       lint: gates,

package/src/Timing.ts

@@ -25,6 +25,10 @@ const TimedRole = Context.Reference<string | undefined>("@llm4ts/flow/Timing/Tim
   defaultValue: () => undefined
 })
 
+/** The role the current call is made for: the caller's, or else `label`. */
+export const roleOr = (label: string): Effect.Effect<string> =>
+  Effect.map(TimedRole, (role) => role ?? label)
+
 /** Times the seat calls `effect` makes under `role` instead of the seat's own label. */
 export const withTimedRole = <A, E, R>(role: string, effect: Effect.Effect<A, E, R>) =>
   Effect.provideService(effect, TimedRole, role)

package/src/Transcript.ts

@@ -0,0 +1,240 @@
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { LlmChunk, Message } from "@llm4ts/core/Models"
+import { redactText } from "@llm4ts/core/observability/Redaction"
+import { roleOr } from "./Timing.ts"
+
+/**
+ * What the model was told and what it answered, per seat call — an opt-in
+ * record (`llm4ts run --transcript`) that `llm4ts watch` tails. It lives in
+ * its own files, never in the trace, so the trace and `llm4ts profile` stay
+ * content-free. Secrets are redacted and every field is capped.
+ */
+
+const Call = Schema.TaggedStruct("Call", {
+  at: Schema.Number,
+  call: Schema.String,
+  role: Schema.String,
+  executor: Schema.optionalKey(Schema.String),
+  /** The system prompt, on a chat's first call only. */
+  system: Schema.optionalKey(Schema.String),
+  /** The input: a chat's newest message, or a one-shot prompt. */
+  input: Schema.String,
+  /** How many messages came before the input (a chat resends them all). */
+  earlier: Schema.optionalKey(Schema.Int)
+})
+
+const Reply = Schema.TaggedStruct("Reply", {
+  at: Schema.Number,
+  call: Schema.String,
+  text: Schema.String
+})
+const Tool = Schema.TaggedStruct("Tool", {
+  at: Schema.Number,
+  call: Schema.String,
+  tool: Schema.String,
+  args: Schema.String
+})
+const ToolResult = Schema.TaggedStruct("ToolResult", {
+  at: Schema.Number,
+  call: Schema.String,
+  output: Schema.String,
+  failed: Schema.optionalKey(Schema.Boolean)
+})
+const End = Schema.TaggedStruct("End", {
+  at: Schema.Number,
+  call: Schema.String,
+  ms: Schema.Number,
+  failed: Schema.optionalKey(Schema.Boolean)
+})
+
+export const TranscriptEntry = Schema.Union([Call, Reply, Tool, ToolResult, End])
+export type TranscriptEntry = typeof TranscriptEntry.Type
+
+/** Where entries go: one stream per story lane, and one for the run. */
+export interface TranscriptSink {
+  readonly write: (lane: string | undefined, entry: TranscriptEntry) => Effect.Effect<void>
+}
+
+export interface MemoryTranscriptSink {
+  readonly sink: TranscriptSink
+  readonly entries: Effect.Effect<
+    ReadonlyArray<{ readonly lane: string | undefined; readonly entry: TranscriptEntry }>
+  >
+}
+
+export const makeMemoryTranscriptSink: Effect.Effect<MemoryTranscriptSink> = Effect.map(
+  Ref.make<ReadonlyArray<{ readonly lane: string | undefined; readonly entry: TranscriptEntry }>>(
+    []
+  ),
+  (entries) => ({
+    sink: { write: (lane, entry) => Ref.update(entries, (all) => [...all, { lane, entry }]) },
+    entries: Ref.get(entries)
+  })
+)
+
+const inputChars = 64_000
+const partChars = 4_000
+
+const clean = (text: string, limit: number): string => redactText(text, { maxLength: limit })
+
+let calls = 0
+const nextCall: Effect.Effect<string> = Effect.sync(() => {
+  calls += 1
+  return `call-${calls}`
+})
+
+export interface TranscriptSeatOptions {
+  readonly lane?: string
+  /** The seat's role; a caller's `withTimedRole` names the call instead. */
+  readonly role: string
+  /** Who serves the seat, read at each call (a roster hands the coder over). */
+  readonly executor?: Effect.Effect<string | undefined>
+}
+
+/** A seat whose every call is written to `sink`, as it happens. */
+export const transcriptSeat = (
+  service: LlmServiceShape,
+  sink: TranscriptSink,
+  options: TranscriptSeatOptions
+): LlmServiceShape => {
+  const write = (entry: TranscriptEntry) => sink.write(options.lane, entry)
+
+  const opened = (
+    input: string,
+    extra: { readonly system?: string; readonly earlier?: number }
+  ): Effect.Effect<{ readonly call: string; readonly start: number }> =>
+    Effect.gen(function* () {
+      const call = yield* nextCall
+      const start = yield* Clock.currentTimeMillis
+      const role = yield* roleOr(options.role)
+      const executor = options.executor === undefined ? undefined : yield* options.executor
+      yield* write({
+        _tag: "Call",
+        at: start,
+        call,
+        role,
+        ...(executor === undefined ? {} : { executor }),
+        ...(extra.system === undefined ? {} : { system: clean(extra.system, inputChars) }),
+        input: clean(input, inputChars),
+        ...(extra.earlier === undefined ? {} : { earlier: extra.earlier })
+      })
+      return { call, start }
+    })
+
+  const closed = (call: string, start: number, failed: boolean): Effect.Effect<void> =>
+    Effect.flatMap(Clock.currentTimeMillis, (at) =>
+      write({ _tag: "End", at, call, ms: at - start, ...(failed ? { failed } : {}) })
+    )
+
+  const chunkEntry = (call: string, chunk: LlmChunk): Effect.Effect<void> =>
+    Effect.flatMap(Clock.currentTimeMillis, (at) => {
+      switch (chunk.metadata.event) {
+        case "tool_use":
+          return write({
+            _tag: "Tool",
+            at,
+            call,
+            tool: chunk.metadata.tool_name ?? chunk.metadata.toolName ?? "",
+            args: clean(chunk.metadata.tool_input ?? chunk.metadata.toolInput ?? "", partChars)
+          })
+        case "tool_result": {
+          const failed =
+            chunk.metadata.tool_failed === "true" || chunk.metadata.tool_status === "error"
+          return write({
+            _tag: "ToolResult",
+            at,
+            call,
+            output: clean(chunk.metadata.tool_content ?? "", partChars),
+            ...(failed ? { failed } : {})
+          })
+        }
+        default:
+          return chunk.delta.length === 0
+            ? Effect.void
+            : write({
+                _tag: "Reply",
+                at,
+                call,
+                text: redactText(chunk.delta, { maxLength: inputChars })
+              })
+      }
+    })
+
+  const recorded = <E>(
+    open: Effect.Effect<{ readonly call: string; readonly start: number }>,
+    stream: Stream.Stream<LlmChunk, E>
+  ): Stream.Stream<LlmChunk, E> =>
+    Stream.unwrap(
+      Effect.map(Effect.all([open, Ref.make(false)]), ([{ call, start }, failed]) =>
+        stream.pipe(
+          Stream.tap((chunk) => chunkEntry(call, chunk)),
+          Stream.tapError(() => Ref.set(failed, true)),
+          Stream.ensuring(Effect.flatMap(Ref.get(failed), (did) => closed(call, start, did)))
+        )
+      )
+    )
+
+  const once = <A, E, R>(input: string, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.flatMap(opened(input, {}), ({ call, start }) =>
+      Effect.onExit(effect, (exit) =>
+        Effect.andThen(
+          Exit.isSuccess(exit)
+            ? Effect.flatMap(Clock.currentTimeMillis, (at) =>
+                write({
+                  _tag: "Reply",
+                  at,
+                  call,
+                  text: clean(JSON.stringify(exit.value) ?? "", inputChars)
+                })
+              )
+            : Effect.void,
+          closed(call, start, Exit.isFailure(exit))
+        )
+      )
+    )
+
+  /** A chat's first call is told everything; a later one only what is new. */
+  const chatInput = (messages: ReadonlyArray<Message>) => {
+    const system = messages.filter((message) => message.role === "System")
+    const rest = messages.filter((message) => message.role !== "System")
+    const first = !rest.some((message) => message.role === "Assistant")
+    const newest = rest.at(-1)?.content ?? ""
+    return first
+      ? {
+          input: rest.map((message) => message.content).join("\n\n"),
+          extra:
+            system.length === 0
+              ? {}
+              : { system: system.map((message) => message.content).join("\n\n") }
+        }
+      : { input: newest, extra: { earlier: rest.length - 1 } }
+  }
+
+  const batched = service.scoreLabelSequence
+  return {
+    executeStream: (prompt) => recorded(opened(prompt, {}), service.executeStream(prompt)),
+    executeStreamWithHistory: (messages) => {
+      const { input, extra } = chatInput(messages)
+      return recorded(opened(input, extra), service.executeStreamWithHistory(messages))
+    },
+    executeWithTools: (prompt, tools) => once(prompt, service.executeWithTools(prompt, tools)),
+    executeStructured: (prompt, schema, jsonSchema) =>
+      once(prompt, service.executeStructured(prompt, schema, jsonSchema)),
+    executeStructuredWithUsage: (prompt, schema, jsonSchema) =>
+      once(prompt, service.executeStructuredWithUsage(prompt, schema, jsonSchema)),
+    scoreLabels: (prompt, labels) => once(prompt, service.scoreLabels(prompt, labels)),
+    ...(batched === undefined
+      ? {}
+      : {
+          scoreLabelSequence: (prompt: string, labelSets: ReadonlyArray<ReadonlyArray<string>>) =>
+            once(prompt, batched(prompt, labelSets))
+        }),
+    isAvailable: service.isAvailable
+  }
+}