@llm4ts/flow 0.13.5 → 0.14.0

package/src/BoardSync.ts

@@ -0,0 +1,358 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import { quoteWiql, type AzureDevOpsToolShape } from "./AzureDevOpsTool.ts"
+import { FlowAborted, type FlowError } from "./FlowError.ts"
+import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
+
+// The progress board of the conversion scenario: a port with the work-item
+// lifecycle (plan → start → complete/fail/skip) and two adapters — a local
+// file board (the default, fully offline: board.json + rendered board.md)
+// and an Azure DevOps adapter (the stretch goal) mapping the same lifecycle
+// onto work items. Flows depend only on the port; which board the client
+// sees is wiring, not policy.
+
+export const BoardVersion = 1
+
+export const BoardStatus = Schema.Literals(["planned", "active", "done", "failed", "skipped"])
+export type BoardStatus = typeof BoardStatus.Type
+
+export class BoardItem extends Schema.Class<BoardItem>("BoardItem")({
+  id: Schema.String,
+  title: Schema.String,
+  wave: Schema.optionalKey(Schema.String),
+  status: BoardStatus,
+  branch: Schema.optionalKey(Schema.String),
+  reportPath: Schema.optionalKey(Schema.String),
+  /** Free-form note: a failure reason, a skip rationale, a triage disposition. */
+  detail: Schema.optionalKey(Schema.String),
+  /** ESTIMATES, never measurements — see EstimatedUsage (ADR 0012). */
+  estimatedTokens: Schema.optionalKey(Schema.Int),
+  estimatedCostUsd: Schema.optionalKey(Schema.Number)
+}) {}
+
+export class Board extends Schema.Class<Board>("Board")({
+  title: Schema.String,
+  items: Schema.Array(BoardItem)
+}) {}
+
+export interface BoardItemResult {
+  readonly branch?: string
+  readonly reportPath?: string
+  readonly detail?: string
+  readonly estimatedTokens?: number
+  readonly estimatedCostUsd?: number
+}
+
+export interface BoardSyncShape {
+  /** Publish the full planned work list. Idempotent: known ids keep their state. */
+  readonly plan: (items: ReadonlyArray<BoardItem>) => Effect.Effect<void, FlowError>
+  readonly start: (id: string) => Effect.Effect<void, FlowError>
+  readonly complete: (id: string, result: BoardItemResult) => Effect.Effect<void, FlowError>
+  readonly fail: (id: string, reason: string) => Effect.Effect<void, FlowError>
+  readonly skip: (id: string, reason: string) => Effect.Effect<void, FlowError>
+  readonly snapshot: Effect.Effect<Board, FlowError>
+}
+
+const sectionOrder: ReadonlyArray<readonly [BoardStatus, string]> = [
+  ["active", "Active"],
+  ["planned", "Planned"],
+  ["done", "Done"],
+  ["failed", "Failed"],
+  ["skipped", "Skipped"]
+]
+
+const itemLine = (item: BoardItem): string => {
+  const parts: Array<string> = [`- **${item.id}** — ${item.title}`]
+  if (item.wave !== undefined) {
+    parts.push(`(wave: ${item.wave})`)
+  }
+  if (item.branch !== undefined) {
+    parts.push(`branch \`${item.branch}\``)
+  }
+  if (item.reportPath !== undefined) {
+    parts.push(`[report](${item.reportPath})`)
+  }
+  if (item.estimatedTokens !== undefined || item.estimatedCostUsd !== undefined) {
+    const tokens = item.estimatedTokens === undefined ? "" : `~${item.estimatedTokens} tokens`
+    const cost = item.estimatedCostUsd === undefined ? "" : `~$${item.estimatedCostUsd.toFixed(2)}`
+    parts.push(`(${[tokens, cost].filter((part) => part.length > 0).join(", ")} — estimated)`)
+  }
+  if (item.detail !== undefined) {
+    parts.push(`— ${item.detail}`)
+  }
+  return parts.join(" ")
+}
+
+/** The markdown board — every figure on it labelled estimated. */
+export const renderBoard = (board: Board): string => {
+  const lines: Array<string> = [`# Board: ${board.title}`, ""]
+  const counts = sectionOrder
+    .map(([status]) => `${status}: ${board.items.filter((item) => item.status === status).length}`)
+    .join(" · ")
+  lines.push(counts, "")
+  lines.push(
+    "All token and cost figures are ESTIMATES (character-count heuristics), not",
+    "measurements.",
+    ""
+  )
+  for (const [status, heading] of sectionOrder) {
+    const items = board.items.filter((item) => item.status === status)
+    if (items.length === 0) {
+      continue
+    }
+    lines.push(`## ${heading}`, "")
+    for (const item of items) {
+      lines.push(itemLine(item))
+    }
+    lines.push("")
+  }
+  return lines.join("\n").trimEnd() + "\n"
+}
+
+const join = (root: string, path: string): string =>
+  `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
+
+const applyResult = (item: BoardItem, status: BoardStatus, result: BoardItemResult): BoardItem =>
+  BoardItem.make({
+    ...item,
+    status,
+    ...(result.branch === undefined ? {} : { branch: result.branch }),
+    ...(result.reportPath === undefined ? {} : { reportPath: result.reportPath }),
+    ...(result.detail === undefined ? {} : { detail: result.detail }),
+    ...(result.estimatedTokens === undefined
+      ? {}
+      : { estimatedTokens: Math.round(result.estimatedTokens) }),
+    ...(result.estimatedCostUsd === undefined ? {} : { estimatedCostUsd: result.estimatedCostUsd })
+  })
+
+/**
+ * The default adapter: `board.json` (versioned) plus a rendered `board.md`
+ * under `directory`. The JSON is the state, the markdown is the demo surface;
+ * both are rewritten on every mutation so a crash never leaves them apart.
+ */
+export const makeLocalBoardSync = (
+  files: PlainFileStoreShape,
+  directory: string,
+  title: string
+): BoardSyncShape => {
+  const jsonPath = join(directory, "board.json")
+  const markdownPath = join(directory, "board.md")
+
+  const load: Effect.Effect<Board, FlowError> = loadVersioned(
+    files,
+    jsonPath,
+    BoardVersion,
+    Board
+  ).pipe(Effect.map((board) => board ?? Board.make({ title, items: [] })))
+
+  const save = (board: Board): Effect.Effect<void, FlowError> =>
+    saveVersioned(files, jsonPath, BoardVersion, Board, board).pipe(
+      Effect.andThen(files.writeAtomic(markdownPath, renderBoard(board)))
+    )
+
+  const update = (
+    id: string,
+    transform: (item: BoardItem) => BoardItem
+  ): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
+      const board = yield* load
+      if (!board.items.some((item) => item.id === id)) {
+        return yield* FlowAborted.make({ message: `board has no item '${id}' — plan it first` })
+      }
+      yield* save(
+        Board.make({
+          ...board,
+          items: board.items.map((item) => (item.id === id ? transform(item) : item))
+        })
+      )
+    })
+
+  return {
+    plan: (items) =>
+      Effect.gen(function* () {
+        const board = yield* load
+        const known = new Map(board.items.map((item) => [item.id, item] as const))
+        // Known ids keep their lived state — re-planning must never demote a
+        // converted page back to "planned".
+        const merged = [...board.items, ...items.filter((item) => !known.has(item.id))]
+        yield* save(Board.make({ title: board.title, items: merged }))
+      }),
+    start: (id) => update(id, (item) => BoardItem.make({ ...item, status: "active" })),
+    complete: (id, result) => update(id, (item) => applyResult(item, "done", result)),
+    fail: (id, reason) =>
+      update(id, (item) => BoardItem.make({ ...item, status: "failed", detail: reason })),
+    skip: (id, reason) =>
+      update(id, (item) => BoardItem.make({ ...item, status: "skipped", detail: reason })),
+    snapshot: load
+  }
+}
+
+/**
+ * Fan one lifecycle out to several boards (local file + ADO, typically).
+ * Mutations hit every board in order; `snapshot` reads the FIRST — the local
+ * board is the source of truth, the others are mirrors.
+ */
+export const composeBoardSync = (boards: ReadonlyArray<BoardSyncShape>): BoardSyncShape => {
+  const first = boards[0]
+  const each = (
+    operation: (board: BoardSyncShape) => Effect.Effect<void, FlowError>
+  ): Effect.Effect<void, FlowError> => Effect.forEach(boards, operation, { discard: true })
+  return {
+    plan: (items) => each((board) => board.plan(items)),
+    start: (id) => each((board) => board.start(id)),
+    complete: (id, result) => each((board) => board.complete(id, result)),
+    fail: (id, reason) => each((board) => board.fail(id, reason)),
+    skip: (id, reason) => each((board) => board.skip(id, reason)),
+    snapshot:
+      first === undefined
+        ? Effect.succeed(Board.make({ title: "empty", items: [] }))
+        : first.snapshot
+  }
+}
+
+export interface AdoBoardOptions {
+  /** Work item type created for each page. Default "Task". */
+  readonly workItemType?: string
+  /** Tag identifying this board's items — the idempotency key. Default "llm4ts-convert". */
+  readonly tag?: string
+  /** Lifecycle → System.State mapping. Defaults: New / Active / Closed. */
+  readonly states?: {
+    readonly planned?: string
+    readonly active?: string
+    readonly done?: string
+  }
+}
+
+const markerQuery = (tag: string, id: string): string =>
+  "SELECT [System.Id] FROM WorkItems WHERE " +
+  `[System.Tags] CONTAINS ${quoteWiql(tag)} AND ` +
+  `[System.Title] CONTAINS ${quoteWiql(`[${id}]`)}`
+
+/**
+ * The stretch adapter (ADR 0012): the same lifecycle mapped onto Azure DevOps
+ * work items through the az-CLI AzureDevOpsTool (ADR 0011). Idempotent by
+ * title marker — `[<id>]` plus the board tag — so a re-run finds its items
+ * instead of duplicating them. Failure and skip are tags plus a comment,
+ * never invented states.
+ */
+export const makeAdoBoardSync = Effect.fn("@llm4ts/flow/BoardSync.makeAdo")(function* (
+  ado: AzureDevOpsToolShape,
+  boardTitle: string,
+  options: AdoBoardOptions = {}
+): Effect.fn.Return<BoardSyncShape> {
+  const workItemType = options.workItemType ?? "Task"
+  const tag = options.tag ?? "llm4ts-convert"
+  const states = {
+    planned: options.states?.planned ?? "New",
+    active: options.states?.active ?? "Active",
+    done: options.states?.done ?? "Closed"
+  }
+  const ids = yield* Ref.make<ReadonlyMap<string, number>>(new Map())
+
+  const lookup = (id: string): Effect.Effect<number, FlowError> =>
+    Effect.gen(function* () {
+      const cached = (yield* Ref.get(ids)).get(id)
+      if (cached !== undefined) {
+        return cached
+      }
+      const found = yield* ado.wiqlIds(markerQuery(tag, id))
+      const first = found[0]
+      if (first === undefined) {
+        return yield* FlowAborted.make({
+          message: `no ADO work item tagged '${tag}' with '[${id}]' in its title — plan it first`
+        })
+      }
+      yield* Ref.update(ids, (current) => new Map(current).set(id, first))
+      return first
+    })
+
+  return {
+    plan: (items) =>
+      Effect.gen(function* () {
+        for (const item of items) {
+          const existing = yield* ado.wiqlIds(markerQuery(tag, item.id))
+          const first = existing[0]
+          if (first !== undefined) {
+            yield* Ref.update(ids, (current) => new Map(current).set(item.id, first))
+            continue
+          }
+          const created = yield* ado.createWorkItem(
+            workItemType,
+            `[${item.id}] ${item.title}`,
+            item.detail ?? item.title,
+            [tag]
+          )
+          yield* Ref.update(ids, (current) => new Map(current).set(item.id, created.id))
+          if (states.planned !== "New") {
+            yield* ado.setState(created.id, states.planned)
+          }
+        }
+      }),
+    start: (id) =>
+      Effect.gen(function* () {
+        const workItem = yield* lookup(id)
+        yield* ado.setState(workItem, states.active)
+      }),
+    complete: (id, result) =>
+      Effect.gen(function* () {
+        const workItem = yield* lookup(id)
+        const parts = [
+          result.branch === undefined ? undefined : `Branch: ${result.branch}`,
+          result.reportPath === undefined ? undefined : `Report: ${result.reportPath}`,
+          result.estimatedTokens === undefined
+            ? undefined
+            : `~${Math.round(result.estimatedTokens)} tokens (estimated)`,
+          result.estimatedCostUsd === undefined
+            ? undefined
+            : `~$${result.estimatedCostUsd.toFixed(2)} (estimated)`,
+          result.detail
+        ].filter((part): part is string => part !== undefined)
+        if (parts.length > 0) {
+          yield* ado.writeComment(workItem, parts.join("\n"))
+        }
+        yield* ado.setState(workItem, states.done)
+      }),
+    fail: (id, reason) =>
+      Effect.gen(function* () {
+        const workItem = yield* lookup(id)
+        yield* ado.editTags(workItem, [`${tag}-failed`], [])
+        yield* ado.writeComment(workItem, `FAILED: ${reason}`)
+      }),
+    skip: (id, reason) =>
+      Effect.gen(function* () {
+        const workItem = yield* lookup(id)
+        yield* ado.editTags(workItem, [`${tag}-skipped`], [])
+        yield* ado.writeComment(workItem, `SKIPPED: ${reason}`)
+      }),
+    snapshot: Effect.gen(function* () {
+      const found = yield* ado.wiqlIds(
+        `SELECT [System.Id] FROM WorkItems WHERE [System.Tags] CONTAINS ${quoteWiql(tag)}`
+      )
+      const items: Array<BoardItem> = []
+      for (const workItemId of found) {
+        const workItem = yield* ado.readWorkItem(workItemId)
+        const match = /^\[([^\]]+)\] (.*)$/.exec(workItem.title)
+        const failed = workItem.tags.includes(`${tag}-failed`)
+        const skipped = workItem.tags.includes(`${tag}-skipped`)
+        const status: BoardStatus = failed
+          ? "failed"
+          : skipped
+            ? "skipped"
+            : workItem.state === states.done
+              ? "done"
+              : workItem.state === states.active
+                ? "active"
+                : "planned"
+        items.push(
+          BoardItem.make({
+            id: match?.[1] ?? String(workItemId),
+            title: match?.[2] ?? workItem.title,
+            status
+          })
+        )
+      }
+      return Board.make({ title: boardTitle, items })
+    })
+  }
+})

package/src/EstimatedUsage.ts

@@ -0,0 +1,180 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
+import type { LlmError } from "@llm4ts/core/Errors"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import { LlmChunk, TokenUsage, type Message } from "@llm4ts/core/Models"
+import { estimateCostUsd } from "./PriceList.ts"
+
+// ESTIMATED token accounting for connectors that report none (every CLI
+// connector: `makeCliConnector` returns no usage at all). The decorator
+// counts characters on both sides of each request and, when the backend
+// reported nothing, appends a synthetic final chunk carrying the estimate —
+// so `collect`, `Chat`, `CostTracker`, and the cost summary all see it
+// through the normal event path, labelled `estimated:<model>` so no report
+// can mistake it for measured usage (ADR 0012; the PoC decision of
+// 2026-08-30 is estimates-only, no CLI usage parsing).
+
+export interface EstimatedUsageOptions {
+  /** Pricing reference for the estimate — a `PriceList` model prefix. */
+  readonly referenceModel: string
+  /** Characters per token for the estimate. Default 4. */
+  readonly charsPerToken?: number
+}
+
+export const defaultReferenceModel = "claude-sonnet-4"
+
+export const estimatedUsageOptionsFromEnv = (
+  environment: Readonly<Record<string, string | undefined>>
+): EstimatedUsageOptions => {
+  const parsed = Number.parseInt(environment.LLM4TS_ESTIMATE_CHARS_PER_TOKEN ?? "", 10)
+  return {
+    referenceModel: environment.LLM4TS_ESTIMATE_MODEL?.trim() || defaultReferenceModel,
+    ...(Number.isFinite(parsed) && parsed > 0 ? { charsPerToken: parsed } : {})
+  }
+}
+
+/** The model label estimates are published under — never a real model id. */
+export const estimatedModelLabel = (referenceModel: string): string => `estimated:${referenceModel}`
+
+export const isEstimatedModel = (model: string | undefined): boolean =>
+  model !== undefined && model.startsWith("estimated:")
+
+const tokensFor = (chars: number, charsPerToken: number): number =>
+  Math.ceil(Math.max(0, chars) / charsPerToken)
+
+export const estimateUsage = (
+  promptChars: number,
+  completionChars: number,
+  options: EstimatedUsageOptions
+): TokenUsage => {
+  const charsPerToken = options.charsPerToken ?? 4
+  const prompt = tokensFor(promptChars, charsPerToken)
+  const completion = tokensFor(completionChars, charsPerToken)
+  const base = TokenUsage.make({ prompt, completion, total: prompt + completion })
+  const costUsd = estimateCostUsd(options.referenceModel, base)
+  return costUsd === undefined ? base : TokenUsage.make({ ...base, costUsd })
+}
+
+const messagesChars = (messages: ReadonlyArray<Message>): number =>
+  messages.reduce((sum, message) => sum + message.content.length, 0)
+
+const mergeTotals = (previous: TokenUsage | undefined, usage: TokenUsage): TokenUsage => {
+  const cached = [previous?.cached, usage.cached].flatMap((value) =>
+    value === undefined ? [] : [value]
+  )
+  const cost = [previous?.costUsd, usage.costUsd].flatMap((value) =>
+    value === undefined ? [] : [value]
+  )
+  return TokenUsage.make({
+    prompt: (previous?.prompt ?? 0) + usage.prompt,
+    completion: (previous?.completion ?? 0) + usage.completion,
+    total: (previous?.total ?? 0) + usage.total,
+    ...(cached.length === 0 ? {} : { cached: cached.reduce((sum, value) => sum + value, 0) }),
+    ...(cost.length === 0 ? {} : { costUsd: cost.reduce((sum, value) => sum + value, 0) })
+  })
+}
+
+export interface EstimatedUsageMeter {
+  /** The decorated service — use this in place of the raw connector. */
+  readonly service: LlmServiceShape
+  /** Cumulative usage seen so far: backend-reported where present, estimated otherwise. */
+  readonly totals: Effect.Effect<TokenUsage | undefined>
+}
+
+const estimatedStream = (
+  stream: Stream.Stream<LlmChunk, LlmError>,
+  promptChars: number,
+  options: EstimatedUsageOptions,
+  record: (usage: TokenUsage) => Effect.Effect<void>
+): Stream.Stream<LlmChunk, LlmError> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const sawUsage = yield* Ref.make(false)
+      const completionChars = yield* Ref.make(0)
+      const tapped = stream.pipe(
+        Stream.tap((chunk) =>
+          Effect.gen(function* () {
+            yield* Ref.update(completionChars, (count) => count + chunk.delta.length)
+            if (chunk.usage !== undefined) {
+              yield* Ref.set(sawUsage, true)
+              yield* record(chunk.usage)
+            }
+          })
+        )
+      )
+      // Appended only after a SUCCESSFUL stream that reported nothing: a
+      // failed request estimates nothing, and a backend that reported real
+      // usage is never double-counted.
+      const tail: Stream.Stream<LlmChunk, LlmError> = Stream.unwrap(
+        Effect.gen(function* () {
+          if (yield* Ref.get(sawUsage)) {
+            return Stream.empty
+          }
+          const usage = estimateUsage(promptChars, yield* Ref.get(completionChars), options)
+          yield* record(usage)
+          return Stream.succeed(
+            LlmChunk.make({
+              delta: "",
+              usage,
+              metadata: { model: estimatedModelLabel(options.referenceModel) }
+            })
+          )
+        })
+      )
+      return Stream.concat(tapped, tail)
+    })
+  )
+
+/**
+ * Decorates a service so every request yields usage — real when the backend
+ * reported it, estimated (and labelled so) when it did not — and exposes the
+ * running totals for per-run reports.
+ */
+export const makeEstimatedUsageMeter = Effect.fn("@llm4ts/flow/EstimatedUsage.make")(function* (
+  service: LlmServiceShape,
+  options: EstimatedUsageOptions
+): Effect.fn.Return<EstimatedUsageMeter> {
+  const totals = yield* Ref.make<TokenUsage | undefined>(undefined)
+  const record = (usage: TokenUsage): Effect.Effect<void> =>
+    Ref.update(totals, (previous) => mergeTotals(previous, usage))
+
+  const decorated: LlmServiceShape = {
+    executeStream: (prompt) =>
+      estimatedStream(service.executeStream(prompt), prompt.length, options, record),
+    executeStreamWithHistory: (messages) =>
+      estimatedStream(
+        service.executeStreamWithHistory(messages),
+        messagesChars(messages),
+        options,
+        record
+      ),
+    executeWithTools: (prompt, tools) => service.executeWithTools(prompt, tools),
+    executeStructured: (prompt, schema, jsonSchema) =>
+      service
+        .executeStructured(prompt, schema, jsonSchema)
+        .pipe(
+          Effect.tap((value) =>
+            record(estimateUsage(prompt.length, (JSON.stringify(value) ?? "").length, options))
+          )
+        ),
+    executeStructuredWithUsage: (prompt, schema, jsonSchema) =>
+      service.executeStructuredWithUsage(prompt, schema, jsonSchema).pipe(
+        Effect.flatMap(([value, usage, model]) => {
+          if (usage !== undefined) {
+            return record(usage).pipe(Effect.as([value, usage, model] as const))
+          }
+          const estimated = estimateUsage(
+            prompt.length,
+            (JSON.stringify(value) ?? "").length,
+            options
+          )
+          return record(estimated).pipe(
+            Effect.as([value, estimated, estimatedModelLabel(options.referenceModel)] as const)
+          )
+        })
+      ),
+    isAvailable: service.isAvailable
+  }
+  return { service: decorated, totals: Ref.get(totals) }
+})

package/src/Pack.ts

@@ -21,6 +21,10 @@ export interface Pack {
   readonly source: string
   readonly scaffold: string | undefined
   readonly sources: string | undefined
+  // Regex over repo-relative paths that `sources:` matches but the estate
+  // does not own: vendored copies, generated exports, test doubles. Excluded
+  // paths never enter the survey graph or the extraction inventory.
+  readonly exclude: string | undefined
   readonly programs: string | undefined
   readonly specsDir: string
   readonly featuresDir: string
@@ -202,11 +206,18 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
       message: `pack manifest 'programFiles:' is not a valid regex template: ${programFiles}`
     })
   }
+  const exclude = fields.exclude
+  if (exclude !== undefined && !isValidRegExp(exclude)) {
+    return yield* PlanParseError.make({
+      message: `pack manifest 'exclude:' is not a valid regex: ${exclude}`
+    })
+  }
   const pack: Pack = {
     name: manifest.name,
     source: fields.source ?? "",
     scaffold: fields.scaffold,
     sources: fields.sources,
+    exclude,
     programs: fields.programs,
     specsDir: fields["specs-dir"] ?? "docs/specs",
     featuresDir: fields["features-dir"] ?? "features",