@llm4ts/flow 2.23.0 → 2.25.0

package/dist/Transcript.js

@@ -0,0 +1,158 @@
+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 { redactText } from "@llm4ts/core/observability/Redaction";
+import { roleOr } from "./Timing.js";
+/**
+ * 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 const makeMemoryTranscriptSink = Effect.map(Ref.make([]), (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, limit) => redactText(text, { maxLength: limit });
+let calls = 0;
+const nextCall = Effect.sync(() => {
+    calls += 1;
+    return `call-${calls}`;
+});
+/** A seat whose every call is written to `sink`, as it happens. */
+export const transcriptSeat = (service, sink, options) => {
+    const write = (entry) => sink.write(options.lane, entry);
+    const opened = (input, extra) => 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, start, failed) => Effect.flatMap(Clock.currentTimeMillis, (at) => write({ _tag: "End", at, call, ms: at - start, ...(failed ? { failed } : {}) }));
+    const chunkEntry = (call, chunk) => 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 = (open, stream) => 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 = (input, effect) => 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) => {
+        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, labelSets) => once(prompt, batched(prompt, labelSets))
+            }),
+        isAvailable: service.isAvailable
+    };
+};
+//# sourceMappingURL=Transcript.js.map

package/dist/Transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transcript.js","sourceRoot":"","sources":["../src/Transcript.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -56,6 +56,7 @@
     "./Judgment": "./dist/Judgment.js",
     "./JudgmentLog": "./dist/JudgmentLog.js",
     "./Perimeter": "./dist/Perimeter.js",
+    "./NodePreflight": "./dist/NodePreflight.js",
     "./Persistence": "./dist/Persistence.js",
     "./Plan": "./dist/Plan.js",
     "./PlanExecution": "./dist/PlanExecution.js",
@@ -76,6 +77,7 @@
     "./StoryPlan": "./dist/StoryPlan.js",
     "./Survey": "./dist/Survey.js",
     "./Timing": "./dist/Timing.js",
+    "./Transcript": "./dist/Transcript.js",
     "./TransientRetry": "./dist/TransientRetry.js",
     "./Usage": "./dist/Usage.js",
     "./Wall": "./dist/Wall.js",
@@ -107,7 +109,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.23.0"
+    "@llm4ts/core": "2.25.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/FlowContext.ts

@@ -25,6 +25,13 @@ export interface FlowContextShape {
   readonly hosting: GitHubToolShape
   readonly events: FlowEventsShape
   readonly reviewers: ReadonlyArray<LlmServiceShape>
+  /**
+   * The judgment seat as a chat service, for the rubric judges that predate
+   * ADR 0017: the reasoner with its tools taken away wherever the harness
+   * can (a roster's judge role, or `readOnly` over a CLI reasoner). Absent
+   * on a context built by hand; judges then fall back to `reasoning`.
+   */
+  readonly judge?: LlmServiceShape
   readonly coderCapabilities: ConnectorCapabilities
   readonly userPrompt: string
   readonly workDir: string

package/src/Judgment.ts

@@ -108,9 +108,9 @@ export const decide = (
   return certainty >= bands.act ? "act" : certainty < bands.hold ? "hold" : "caution"
 }
 
-/** The context's judgment service, or one derived from its reasoning seat. */
+/** The context's judgment service, or one derived from its judge (else reasoning) seat. */
 export const judgmentOf = (context: FlowContextShape): JudgmentShape =>
-  context.judgment ?? makeLlmJudgment(context.reasoning)
+  context.judgment ?? makeLlmJudgment(context.judge ?? context.reasoning)
 
 const backendFailure = (error: JudgmentBackendError): FlowError =>
   FlowLlmError.from(ProviderError.make({ message: error.message, cause: error }))

package/src/NodePreflight.ts

@@ -0,0 +1,316 @@
+/**
+ * Which Node will the gates run on, and is it the one the application pins?
+ *
+ * Gates (`pnpm lint`, `pnpm test`, `pnpm build`) are spawned with the
+ * environment llm4ts inherited, so `pnpm` finds the `node` on PATH, which is
+ * whatever shell launched llm4ts, not what the application asks for in
+ * `.nvmrc`, `.node-version` or `package.json#engines`. A mismatch surfaces as
+ * a red gate on the first story, in a syntax error or an engine refusal that
+ * says nothing about Node. This asks before the first gate, and names both.
+ *
+ * pnpm's `use-node-version` (`.npmrc`) makes pnpm fetch and run that Node
+ * itself, so a target that carries it passes regardless of PATH.
+ */
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import { FlowAborted, type FlowError } from "./FlowError.ts"
+import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+/** A Node pin as the application wrote it, and where. */
+export class NodePin extends Schema.Class<NodePin>("NodePin")({
+  spec: Schema.String,
+  source: Schema.String
+}) {}
+
+// ---- Version matching ---------------------------------------------------------------
+
+type Partial = {
+  readonly major: number
+  readonly minor?: number
+  readonly patch?: number
+}
+
+const partialOf = (text: string): Partial | undefined => {
+  const match = /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/.exec(text.trim())
+  if (match === null || match[1] === undefined) {
+    return undefined
+  }
+  const component = (value: string | undefined): number | undefined =>
+    value === undefined || value === "x" || value === "*" ? undefined : Number(value)
+  const minor = component(match[2])
+  const patch = component(match[3])
+  return {
+    major: Number(match[1]),
+    ...(minor === undefined ? {} : { minor }),
+    ...(patch === undefined ? {} : { patch })
+  }
+}
+
+const triple = (version: Partial): ReadonlyArray<number> => [
+  version.major,
+  version.minor ?? 0,
+  version.patch ?? 0
+]
+
+const compare = (left: ReadonlyArray<number>, right: ReadonlyArray<number>): number => {
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0)
+    if (difference !== 0) {
+      return difference
+    }
+  }
+  return 0
+}
+
+/** The alias forms only a version manager resolves (`lts/*`, `lts/iron`, `node`). */
+const isAlias = (spec: string): boolean =>
+  /^(lts\/.*|node|latest|stable|current|system)$/i.test(spec)
+
+const tokenHolds = (version: ReadonlyArray<number>, token: string): boolean | undefined => {
+  if (token === "*" || token === "x" || token === "latest") {
+    return true
+  }
+  const match = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(token)
+  const operator = match?.[1] ?? ""
+  const partial = partialOf(match?.[2] ?? "")
+  if (partial === undefined) {
+    return undefined
+  }
+  const low = triple(partial)
+  switch (operator) {
+    case ">=":
+      return compare(version, low) >= 0
+    case ">":
+      return compare(version, low) > 0
+    case "<":
+      return compare(version, low) < 0
+    case "<=":
+      return compare(version, low) <= 0
+    case "^": {
+      const high =
+        partial.major > 0
+          ? [partial.major + 1, 0, 0]
+          : partial.minor !== undefined && partial.minor > 0
+            ? [0, partial.minor + 1, 0]
+            : [0, 0, (partial.patch ?? 0) + 1]
+      return compare(version, low) >= 0 && compare(version, high) < 0
+    }
+    case "~": {
+      const high =
+        partial.minor === undefined
+          ? [partial.major + 1, 0, 0]
+          : [partial.major, partial.minor + 1, 0]
+      return compare(version, low) >= 0 && compare(version, high) < 0
+    }
+    default: {
+      // A bare pin matches on the components it names: "20" is any 20.x.y.
+      const [major, minor, patch] = version
+      return (
+        major === partial.major &&
+        (partial.minor === undefined || minor === partial.minor) &&
+        (partial.patch === undefined || patch === partial.patch)
+      )
+    }
+  }
+}
+
+/**
+ * Whether a Node version (`v24.12.0`) satisfies a pin as `.nvmrc`, `engines`
+ * or corepack write them; `undefined` when the pin is an alias or a form
+ * this cannot read, which is a reason to say so, not to fail.
+ */
+export const nodeVersionSatisfies = (version: string, spec: string): boolean | undefined => {
+  const trimmed = spec.trim()
+  const have = partialOf(version)
+  if (have === undefined || isAlias(trimmed)) {
+    return undefined
+  }
+  const actual = triple(have)
+  let unknown = false
+  const clauses = trimmed.split("||").map((clause) => clause.trim())
+  for (const clause of clauses) {
+    const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(clause)
+    const tokens =
+      hyphen?.[1] !== undefined && hyphen[2] !== undefined
+        ? [`>=${hyphen[1]}`, `<=${hyphen[2]}`]
+        : clause.split(/\s+/).filter((token) => token.length > 0)
+    const verdicts = tokens.map((token) => tokenHolds(actual, token))
+    if (verdicts.some((verdict) => verdict === undefined)) {
+      unknown = true
+      continue
+    }
+    if (verdicts.every((verdict) => verdict === true)) {
+      return true
+    }
+  }
+  return unknown ? undefined : false
+}
+
+// ---- Reading the pins ------------------------------------------------------------------
+
+const PackageEngines = Schema.fromJsonString(
+  Schema.Struct({
+    engines: Schema.optionalKey(Schema.Struct({ node: Schema.optionalKey(Schema.String) }))
+  })
+)
+
+const readOptional = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<string | undefined> =>
+  files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+const firstLine = (text: string): string =>
+  text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/#.*$/, "").trim())
+    .find((line) => line.length > 0) ?? ""
+
+/** The Node pins in an application directory: `.nvmrc`, `.node-version`, `engines.node`. */
+export const nodePinsOf = (
+  files: PlainFileStoreShape,
+  appDir: string
+): Effect.Effect<ReadonlyArray<NodePin>> =>
+  Effect.gen(function* () {
+    const pins: Array<NodePin> = []
+    for (const source of [".nvmrc", ".node-version"]) {
+      const text = yield* readOptional(files, join(appDir, source))
+      const spec = text === undefined ? "" : firstLine(text)
+      if (spec.length > 0) {
+        pins.push(NodePin.make({ spec, source }))
+      }
+    }
+    const manifest = yield* readOptional(files, join(appDir, "package.json"))
+    if (manifest !== undefined) {
+      const engines = yield* Schema.decodeUnknownEffect(PackageEngines)(manifest).pipe(
+        Effect.map((parsed) => parsed.engines?.node?.trim()),
+        Effect.catch(() => Effect.succeed(undefined))
+      )
+      if (engines !== undefined && engines.length > 0) {
+        pins.push(NodePin.make({ spec: engines, source: "package.json engines.node" }))
+      }
+    }
+    return pins
+  })
+
+/** pnpm's `use-node-version` from the application's `.npmrc`, when it carries one. */
+export const pnpmNodeVersionOf = (
+  files: PlainFileStoreShape,
+  appDir: string
+): Effect.Effect<string | undefined> =>
+  Effect.map(readOptional(files, join(appDir, ".npmrc")), (text) => {
+    for (const line of (text ?? "").split(/\r?\n/)) {
+      const match = /^\s*use-node-version\s*=\s*(\S+)/.exec(line)
+      if (match?.[1] !== undefined) {
+        return match[1]
+      }
+    }
+    return undefined
+  })
+
+// ---- The report ---------------------------------------------------------------------------
+
+export type NodePreflightReport =
+  | { readonly _tag: "Off"; readonly summary: string }
+  | { readonly _tag: "NoPin"; readonly summary: string }
+  | { readonly _tag: "Managed"; readonly node: string; readonly summary: string }
+  | { readonly _tag: "NoNode"; readonly summary: string }
+  | {
+      readonly _tag: "Mismatch"
+      readonly node: string
+      readonly unmet: ReadonlyArray<NodePin>
+      readonly summary: string
+    }
+  | { readonly _tag: "Ok"; readonly node: string; readonly summary: string }
+
+const switchedOff = (value: string | undefined): boolean =>
+  value !== undefined && ["off", "0", "false", "no"].includes(value.trim().toLowerCase())
+
+const describePin = (pin: NodePin): string => `${pin.spec} (${pin.source})`
+
+/**
+ * Compares the Node the gates would run on — `node --version` through the
+ * same executor and PATH the gates get — with the application's pins.
+ * `LLM4TS_NODE_CHECK=off` skips it.
+ */
+export const nodePreflightReport = Effect.fn("@llm4ts/flow/NodePreflight.report")(function* (
+  process: ProcessExecutorShape,
+  files: PlainFileStoreShape,
+  appDir: string,
+  environment: Readonly<Record<string, string | undefined>>
+): Effect.fn.Return<NodePreflightReport> {
+  if (switchedOff(environment.LLM4TS_NODE_CHECK)) {
+    return { _tag: "Off", summary: "node: check off (LLM4TS_NODE_CHECK)" }
+  }
+  const pins = yield* nodePinsOf(files, appDir)
+  if (pins.length === 0) {
+    return {
+      _tag: "NoPin",
+      summary: `node: ${appDir} pins no version (.nvmrc, .node-version, package.json engines.node)`
+    }
+  }
+  const managed = yield* pnpmNodeVersionOf(files, appDir)
+  if (managed !== undefined) {
+    return {
+      _tag: "Managed",
+      node: managed,
+      summary: `node: pnpm runs the gates on Node ${managed} (use-node-version in .npmrc)`
+    }
+  }
+  const probed = yield* process.run(["node", "--version"], appDir, {}).pipe(
+    Effect.map((result) => (result.exitCode === 0 ? result.stdout.join("").trim() : undefined)),
+    Effect.catch(() => Effect.succeed(undefined))
+  )
+  if (probed === undefined || probed.length === 0) {
+    return {
+      _tag: "NoNode",
+      summary:
+        `node: not on the PATH the gates inherit, though ${appDir} pins ` +
+        `${pins.map(describePin).join(", ")}; launch llm4ts from a shell with node on PATH`
+    }
+  }
+  const unmet = pins.filter((pin) => nodeVersionSatisfies(probed, pin.spec) === false)
+  const unchecked = pins.filter((pin) => nodeVersionSatisfies(probed, pin.spec) === undefined)
+  if (unmet.length > 0) {
+    return {
+      _tag: "Mismatch",
+      node: probed,
+      unmet,
+      summary:
+        `node: the gates would run on Node ${probed} (the node on PATH), but ${appDir} pins ` +
+        `${unmet.map(describePin).join(", ")}. Launch llm4ts under a matching Node ` +
+        "(nvm use / fnm use), or add use-node-version=<x.y.z> to the application's .npmrc " +
+        "so pnpm fetches it, or set LLM4TS_NODE_CHECK=off to run anyway"
+    }
+  }
+  return {
+    _tag: "Ok",
+    node: probed,
+    summary:
+      `node: ${probed} satisfies ${pins
+        .filter((pin) => !unchecked.includes(pin))
+        .map(describePin)
+        .join(", ")}` +
+      (unchecked.length === 0
+        ? ""
+        : `; ${unchecked.map(describePin).join(", ")} not checked (an alias only a version manager resolves)`)
+  }
+})
+
+/** The report on the run's events, or the run aborted before its first gate. */
+export const nodePreflight = Effect.fn("@llm4ts/flow/NodePreflight.nodePreflight")(function* (
+  process: ProcessExecutorShape,
+  files: PlainFileStoreShape,
+  events: FlowEventsShape,
+  appDir: string,
+  environment: Readonly<Record<string, string | undefined>>
+): Effect.fn.Return<void, FlowError> {
+  const report = yield* nodePreflightReport(process, files, appDir, environment)
+  if (report._tag === "Mismatch" || report._tag === "NoNode") {
+    return yield* FlowAborted.make({ message: report.summary })
+  }
+  yield* events.publish(Info.make({ message: report.summary }))
+})

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)