@loomwork/llm 0.0.0-stage → 0.1.0

package/src/assembleStream.ts

@@ -0,0 +1,219 @@
+import { fail } from "@loomwork/core";
+import type { LlmResponse, LlmStreamChunk } from "./types";
+
+// ── The streamed-≡-completed contract ─────────────────────────────────────────
+//
+// Two paths to one outcome need a rule saying they agree, or they drift and the
+// drift shows up as an agent that behaves differently once streaming is switched
+// on. ADR 0059 D1 set the precedent for content: a streamed address MUST equal
+// the whole-buffer address. This is the same discipline for the model call —
+// assembling a stream MUST produce what `complete` would have returned.
+//
+// Assembly is deliberately dumb: concatenate the deltas, take the outcome fields
+// from the terminal chunk. Anything cleverer would be a place for the two paths
+// to disagree.
+
+/** Thrown when a stream violates its shape contract (no terminal chunk, or more than one). */
+export class MalformedStreamError extends Error {
+  constructor(message: string) {
+    super(`Malformed LLM stream: ${message}`);
+    this.name = "MalformedStreamError";
+  }
+}
+
+/**
+ * Fold a completed stream into the `LlmResponse` it represents.
+ *
+ * `stopReason` defaults to `"end_turn"` when the provider does not report one —
+ * the same value `complete` yields for an unrecognised stop reason, so a
+ * text-only streaming provider assembles to the same shape it always would.
+ * `toolCalls` and `usage` stay ABSENT rather than becoming empty: `undefined`
+ * means "not reported", `[]` would mean "reported none", and metering must be
+ * able to tell a provider that omits usage from one that charged nothing.
+ */
+export function assembleStream(chunks: readonly LlmStreamChunk[]): LlmResponse {
+  const terminals = chunks.filter((c) => c.done);
+  if (terminals.length === 0) {
+    throw new MalformedStreamError("no terminal chunk (none had done: true)");
+  }
+  if (terminals.length > 1) {
+    throw new MalformedStreamError(`${terminals.length} terminal chunks (exactly one is allowed)`);
+  }
+  const last = chunks[chunks.length - 1];
+  if (last?.done !== true) {
+    throw new MalformedStreamError("the terminal chunk is not last");
+  }
+
+  const content = chunks.map((c) => c.delta).join("");
+  return {
+    content,
+    ...(last.toolCalls !== undefined && { toolCalls: last.toolCalls }),
+    stopReason: last.stopReason ?? "end_turn",
+    ...(last.usage !== undefined && { usage: last.usage }),
+    ...(last.reasoning !== undefined && { reasoning: last.reasoning }),
+    ...(last.layout !== undefined && { layout: last.layout }),
+  };
+}
+
+/**
+ * The channel an interrupted generation fails on (ADR 0060). Its payload is
+ * {@link InterruptedGeneration} — the text produced before the abort, which is
+ * usually the most expensive artifact the turn made and was previously discarded:
+ * `complete` + abort throws with the response body unread, so there is nothing to
+ * keep. Only a call that has been accumulating deltas has a partial to hand back.
+ *
+ * Declare it in the owning contract's `errors:` map to get the ADR 0060 treatment
+ * (recorded as `STEP_FAILED { channel, payload }`, substituted on replay);
+ * undeclared, it degrades to an ordinary failure exactly as before.
+ */
+export const LLM_INTERRUPTED = "llmInterrupted";
+
+export interface InterruptedGeneration {
+  /** Deltas received before the abort, concatenated. May be empty. */
+  content: string;
+  /** Usage, if the provider reported any before the interruption. */
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+/** What a stream has produced so far, offered to {@link CollectStreamOptions.guard}. */
+export interface StreamProgress {
+  /** Everything received so far, concatenated. */
+  text: string;
+  /** Number of deltas received. */
+  deltas: number;
+  /** Usage, if the provider has reported any yet. Most report only at the end. */
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+export interface CollectStreamOptions {
+  /** When this is aborted, the partial is captured instead of being thrown away. */
+  signal?: AbortSignal;
+  /** Transient sink for deltas as they arrive. Never journaled by this function. */
+  onDelta?: (delta: string) => void;
+  /**
+   * ADR 0133 D6 - transient sink for readable reasoning increments, a channel SEPARATE from
+   * `onDelta` (and never part of `guard`'s `text`, nor of the interrupted partial). Never journaled.
+   */
+  onReasoningDelta?: (delta: string) => void;
+  /** R5 — transient sink for tool-call input fragments. Never journaled. */
+  onToolDelta?: (delta: { id: string; name?: string; inputDelta: string }) => void;
+  /**
+   * Called after every delta. THROW to sever the generation mid-flight — the
+   * throw propagates, the `for await` exits, and the underlying HTTP call is
+   * released.
+   *
+   * This is the seam K8.4 needs and the only one a stream can offer: providers
+   * report usage once at the end, so the sole thing observable *while* a
+   * generation runs is its own output. A guard that throws here is the
+   * difference between paying for a runaway generation and stopping it.
+   *
+   * Deliberately generic — no budget vocabulary lives in this package.
+   * `@loomwork/middleware`'s `streamTokenBudget` builds the budget-shaped one.
+   */
+  guard?: (progress: StreamProgress) => void;
+}
+
+/**
+ * `assembleStream` over a live stream — drains it, feeds deltas out as they
+ * arrive, and folds what arrived.
+ *
+ * With a `signal`, an abort mid-generation is NOT a lost generation: what was
+ * produced is captured as an {@link LLM_INTERRUPTED} typed failure. Anything else
+ * propagates untyped, so a transport failure stays one — K9 retries the turn
+ * whole, and a network blip never reads as a user stop.
+ *
+ * Shared by `createLlmEffect` and `AgentRunner` deliberately: two copies of an
+ * accumulate-and-capture loop is two chances to differ about what "interrupted"
+ * means, and the whole point is that the partial survives identically either way.
+ */
+export async function collectStream(
+  stream: AsyncIterable<LlmStreamChunk>,
+  options: CollectStreamOptions = {}
+): Promise<LlmResponse> {
+  // Only three facts about the stream survive the fold — the text, the terminal
+  // chunk's outcome, and the shape checks — so nothing retains the chunks
+  // themselves. A long generation would otherwise hold one small object per
+  // delta for its whole duration, times every concurrent stream.
+  let count = 0;
+  let terminals = 0;
+  let last: LlmStreamChunk | undefined;
+  // Running state, maintained per chunk rather than recomputed per chunk. The
+  // first cut rebuilt the text with `chunks.map(...).join("")` and rescanned for
+  // usage on EVERY delta, which is O(n²) over a generation: 4,000 deltas cost
+  // ~90ms of pure copying, and `streamTokenBudget`'s `checkEvery` could not help
+  // because the expensive part ran before the guard was ever consulted.
+  // Appending to a string is amortized O(1); tracking the last reported usage is
+  // O(1). The guard is now the only cost per delta.
+  let text = "";
+  let usage: LlmStreamChunk["usage"];
+  // A guard breach is NOT an interruption, and the two are easy to confuse: a
+  // guard that severs typically aborts the execution too, so by the time the
+  // catch below runs, `signal.aborted` is true and the budget error would be
+  // rewritten into "interrupted" — losing the reason the generation stopped.
+  // The caller has to be able to tell "a human stopped this" from "this cost too
+  // much", so the guard's own error is remembered and rethrown untouched.
+  let guardError: unknown;
+  try {
+    for await (const chunk of stream) {
+      count += 1;
+      last = chunk;
+      if (chunk.done) terminals += 1;
+      text += chunk.delta;
+      // Providers report usage late; keep the most recent one seen.
+      if (chunk.usage !== undefined) usage = chunk.usage;
+      // The guard runs BEFORE delivery: a delta that breaches it severs the stream
+      // and is never handed to a sink (ADR 0119 — a live tail must not see what the
+      // guard exists to stop).
+      if (options.guard !== undefined) {
+        try {
+          options.guard({
+            text,
+            deltas: count,
+            ...(usage !== undefined && { usage }),
+          });
+        } catch (err) {
+          guardError = err;
+          throw err;
+        }
+      }
+      // A provider that ignores the signal keeps yielding after an abort; checking
+      // here severs it at the next chunk instead of delivering text to a caller who
+      // has gone (the catch below turns it into the LLM_INTERRUPTED partial).
+      if (options.signal?.aborted === true) {
+        throw options.signal.reason instanceof Error
+          ? options.signal.reason
+          : new Error("generation aborted");
+      }
+      if (chunk.delta !== "") options.onDelta?.(chunk.delta);
+      if (chunk.toolDelta !== undefined) options.onToolDelta?.(chunk.toolDelta);
+      if (chunk.reasoningDelta !== undefined && chunk.reasoningDelta !== "") {
+        options.onReasoningDelta?.(chunk.reasoningDelta);
+      }
+    }
+  } catch (err) {
+    if (guardError !== undefined) throw guardError;
+    if (options.signal?.aborted === true) {
+      const partial: InterruptedGeneration = {
+        content: text,
+        ...(usage !== undefined && { usage }),
+      };
+      fail(LLM_INTERRUPTED, partial, "generation interrupted");
+    }
+    throw err;
+  }
+  // Same contract as `assembleStream`, checked against the counters rather than
+  // a retained array.
+  if (terminals === 0) throw new MalformedStreamError("no terminal chunk (none had done: true)");
+  if (terminals > 1) {
+    throw new MalformedStreamError(`${terminals} terminal chunks (exactly one is allowed)`);
+  }
+  if (last?.done !== true) throw new MalformedStreamError("the terminal chunk is not last");
+  return {
+    content: text,
+    ...(last.toolCalls !== undefined && { toolCalls: last.toolCalls }),
+    stopReason: last.stopReason ?? "end_turn",
+    ...(last.usage !== undefined && { usage: last.usage }),
+    ...(last.reasoning !== undefined && { reasoning: last.reasoning }),
+    ...(last.layout !== undefined && { layout: last.layout }),
+  };
+}

package/src/capabilities.ts

@@ -0,0 +1,96 @@
+import type { LlmContentPart, LlmMediaPart, LlmModality } from "./parts";
+import type { LlmRequest } from "./types";
+
+// ── R5 — what a provider accepts, declared, and refused before the wire ─────
+
+/**
+ * The media types a provider accepts for one modality: a list of exact types
+ * (`image/png`), type wildcards (`image/*`), or `"*"` for any.
+ */
+export type MediaTypeSet = readonly string[];
+
+/** Text and tool calls are always supported; media is opt-in per modality. */
+export interface LlmCapabilities {
+  image?: MediaTypeSet;
+  audio?: MediaTypeSet;
+  file?: MediaTypeSet;
+  /** ADR 0133 - the provider can return model reasoning. Drives the boot warning when no reasoning store is configured. */
+  reasoning?: boolean;
+}
+
+/** Thrown, before any network call, when a request carries a modality the provider did not declare. */
+export class UnsupportedModalityError extends Error {
+  readonly modality: LlmModality;
+  readonly mediaType: string;
+  readonly provider: string | undefined;
+  constructor(modality: LlmModality, mediaType: string, provider?: string) {
+    super(
+      `${provider ?? "This LLM provider"} does not accept ${modality} content of type "${mediaType}" (not in its declared capabilities). The request was refused before any network call.`
+    );
+    this.name = "UnsupportedModalityError";
+    this.modality = modality;
+    this.mediaType = mediaType;
+    this.provider = provider;
+  }
+}
+
+export function mediaTypeAccepted(set: MediaTypeSet | undefined, mediaType: string): boolean {
+  if (set === undefined) return false;
+  const mt = mediaType.toLowerCase();
+  for (const allowed of set) {
+    if (allowed === "*" || allowed.toLowerCase() === mt) return true;
+    if (allowed.endsWith("/*") && mt.startsWith(allowed.slice(0, -1).toLowerCase())) return true;
+  }
+  return false;
+}
+
+function* mediaParts(parts: readonly LlmContentPart[]): Generator<LlmMediaPart> {
+  for (const p of parts) {
+    if (p.type === "image" || p.type === "audio" || p.type === "file") yield p;
+    else if (p.type === "tool_result" && typeof p.content !== "string") {
+      for (const r of p.content) if (r.type !== "text") yield r;
+    }
+  }
+}
+
+/** Every media part in a request, in order (including those inside `tool_result`s). */
+export function* requestMediaParts(request: Pick<LlmRequest, "messages">): Generator<LlmMediaPart> {
+  for (const m of request.messages) {
+    if (typeof m.content !== "string") yield* mediaParts(m.content);
+  }
+}
+
+/**
+ * Refuse a request that uses a modality / media type the provider has not declared.
+ * Pure and cheap (one walk); providers call it at the top of `complete` / `stream` and
+ * `createLlmEffect` calls it before resolving any content, so the refusal precedes
+ * every byte of I/O.
+ */
+export function assertRequestSupported(
+  request: Pick<LlmRequest, "messages">,
+  capabilities: LlmCapabilities | undefined,
+  provider?: string
+): void {
+  for (const p of requestMediaParts(request)) {
+    if (!mediaTypeAccepted(capabilities?.[p.type], p.mediaType)) {
+      throw new UnsupportedModalityError(p.type, p.mediaType, provider);
+    }
+  }
+}
+
+/**
+ * The modalities a shipped provider declares for `model`: an ALLOWLIST. `base` only when the id
+ * matches a family known to take media (`allow`); every other id — unknown, older, a local alias —
+ * declares nothing, so a model that cannot take an image is refused locally instead of 400'd by the
+ * API, and a new family needs one line here before it is trusted with media. `config.capabilities`
+ * always wins (`capabilities: {}` = text-only). A provider on a non-default `baseUrl` (an
+ * OpenAI-compatible server) declares nothing either, since the model id says nothing about what is
+ * behind it; pass `capabilities` to turn media on.
+ */
+export function capabilitiesForModel(
+  model: string,
+  base: LlmCapabilities,
+  allow: readonly RegExp[]
+): LlmCapabilities {
+  return allow.some((re) => re.test(model)) ? base : {};
+}

package/src/createLlmEffect.ts

@@ -0,0 +1,287 @@
+import { type TaintedValue, tainted, unwrapTainted } from "@loomwork/classify";
+import { LlmEffect } from "@loomwork/effect-runtime";
+import type {
+  EffectContext,
+  EffectDelta,
+  EffectReasoningDefaults,
+  EffectReasoningHook,
+} from "@loomwork/effect-runtime";
+import { collectStream } from "./assembleStream";
+import type { StreamProgress } from "./assembleStream";
+import { assertRequestSupported } from "./capabilities";
+import { type LlmReasoningOptions, captureReasoning, reasoningStoreResolver } from "./reasoning";
+import { type ContentResolver, resolveRequestContent } from "./resolveContent";
+import type { LlmCapturedResponse, LlmProvider, LlmRequest, LlmRequestInput } from "./types";
+import { guardRequest } from "./untrusted";
+
+export interface CreateLlmEffectOptions<TIn, TOut> {
+  provider: LlmProvider;
+  buildRequest: (input: TIn, ctx: EffectContext) => LlmRequestInput;
+  parseResponse?: (response: LlmCapturedResponse, input: TIn) => TOut;
+  /**
+   * ADR 0133 - model reasoning as audit evidence. Readable text goes to `store` (a sidecar, never
+   * the step value), `parseResponse` sees only recorded `reasoning` parts (kind, provider,
+   * signature, reference, digest), and one `LLM_REASONING_CAPTURED` event names references and
+   * digests. `capture` defaults to on iff a store is configured; `live` streams readable reasoning
+   * deltas through the governed per-call sink as `{ reasoning }` chunks (off by default).
+   * Unset, an app sees no change except that `response.reasoning` parts appear (signatures only)
+   * when a provider returns reasoning.
+   */
+  reasoning?: LlmReasoningOptions;
+  /**
+   * Consume the provider's `stream` instead of `complete` (R9). OPT-IN: the two
+   * paths return the same outcome by the R8 parity contract, but they are
+   * different wire calls, and an effect that silently changed which one it makes
+   * would be a surprise for anyone already running this.
+   *
+   * Falls back to `complete` when the provider implements no `stream`, so a
+   * provider swap cannot turn this into a runtime failure.
+   *
+   * What streaming buys, given the outcome is identical: deltas reach
+   * {@link onDelta} as they arrive, and an interrupted generation keeps its
+   * partial text ({@link LLM_INTERRUPTED}).
+   */
+  stream?: boolean;
+  /**
+   * R5 — fetch the bytes behind a `{ kind: "ref" }` media source, at call time. The
+   * journaled request carries only the address; this is the one place bytes appear, and
+   * only on a LIVE call (a replay is served from the log and never reaches it). Typically
+   * `(ref) => contentStore.get({ __loomContent: ref.address })`. Without it, a request
+   * with a ref is refused (`UnresolvedContentError`) before any network call.
+   */
+  resolveContent?: ContentResolver;
+  /** R5 — cap on one inline media part, decoded. Default 64 KiB (`MAX_INLINE_BYTES`). */
+  maxInlineBytes?: number;
+  /** R5 — cap on ALL inline media in one request. Default 256 KiB (`MAX_INLINE_TOTAL_BYTES`). */
+  maxInlineTotalBytes?: number;
+  /** R5 — cap on the total bytes `resolveContent` may return for one request. Default 32 MiB. */
+  maxResolvedBytes?: number;
+  /**
+   * R5 — a sink for streamed tool-call INPUT fragments (`id`, `name` on the first, then
+   * partial JSON). Transient and bare: it is NOT routed through the governed `ctx.onDelta`
+   * channel (ADR 0119), because middleware delta guards inspect text. Streaming only.
+   */
+  onToolDelta?: (
+    delta: { id: string; name?: string; inputDelta: string },
+    ctx: EffectContext
+  ) => void;
+  /**
+   * R5 — a retried attempt `attempt` (> 1) is about to stream: discard the fragments
+   * {@link onToolDelta} delivered so far (the same contract as {@link onReset} for text). Called
+   * once per retry, via the same runtime reset chunk as `onReset`. Like `onToolDelta`, it sits OUTSIDE the governed
+   * channel: no middleware delta guard or output validator sees tool-input fragments, and
+   * `streamTokenBudget` meters the text only.
+   */
+  onToolReset?: (attempt: number, ctx: EffectContext) => void;
+  /**
+   * Where deltas go. TRANSIENT by construction — this effect never journals them,
+   * and must not: chunks-as-events is the fold-economics problem ST-R rejected,
+   * and `ctx.stream` is durable PER DELTA (one permanent event each), so routing
+   * a token stream through it is a choice an author makes deliberately, at a
+   * granularity they pick.
+   *
+   * The natural sink is `progressHub` (or the app's own `onDelta` handler). `@loomwork/live-query`
+   * is NOT such a sink: it has no delta-push API — `subscribe` re-folds DURABLE events
+   * (`snapshot` + `EventStore.subscribe`), so there is nothing there to push a per-token
+   * delta into (2026-09-27 audit).
+   *
+   * Not called on replay: a completed effect is served from the log and never
+   * re-invoked, so a tail attached to a replay sees silence.
+   *
+   * ADR 0119 — under an `EffectRuntime` this sink is GOVERNED: it receives a delta only
+   * after every middleware delta guard accepted it (a PII/output validator severs the
+   * stream before the breaching delta), on durable and transient calls alike, and it
+   * receives NOTHING when a middleware `inspectsOutput` without a delta form (the call
+   * completes non-streamed). Used bare (no runtime) it is called directly.
+   *
+   * A per-call sink (`EffectContext.onDelta` — what `DecideScope.invokeTransient`
+   * `{ onDelta }` sets) is called IN ADDITION to this one, with `{ delta }` per delta and a
+   * final `{ delta: "", done: true, usage }`.
+   */
+  onDelta?: (delta: string, ctx: EffectContext) => void;
+  /**
+   * ADR 0119 — called when a retried attempt `attempt` (> 1) begins: discard what
+   * {@link onDelta} delivered so far. Same governed delivery as `onDelta`.
+   */
+  onReset?: (attempt: number, ctx: EffectContext) => void;
+  /**
+   * K8.4 — a mid-flight guard, called after every delta; THROW to sever the
+   * generation. Curried over the effect context so it can read `ctx.resources`
+   * and emit a durable fact before throwing.
+   *
+   * `@loomwork/middleware`'s `streamTokenBudget(budget)` is the budget-shaped one.
+   * Streaming-only by nature: `complete` produces nothing to observe until it is
+   * already finished, which is the whole reason K8.4 waited on streaming effects.
+   */
+  guard?: (ctx: EffectContext) => (progress: StreamProgress) => void;
+}
+
+function reasoningResolverOf(r: LlmReasoningOptions | undefined): ContentResolver | undefined {
+  return r?.resolve ?? (r?.store !== undefined ? reasoningStoreResolver(r.store) : undefined);
+}
+
+export function createLlmEffect<TIn = string, TOut = string>(
+  options: CreateLlmEffectOptions<TIn, TOut>
+): LlmEffect<TIn, TOut> {
+  const parse = options.parseResponse ?? ((r: LlmCapturedResponse) => r.content as unknown as TOut);
+  // ADR 0133 D7 - the app's defaults (`observability.reasoning`) are adopted at boot; the effect's own
+  // options win field by field. Resolved per call, so an adoption after construction takes effect.
+  let adopted: EffectReasoningDefaults | false | undefined;
+  const reasoningOf = (): LlmReasoningOptions | undefined =>
+    adopted === undefined && options.reasoning === undefined
+      ? undefined
+      : adopted === false
+        ? // The app-wide `false` is a default for effects with NO policy of their own: an effect that
+          // configured its own store or capture choice keeps it entirely.
+          options.reasoning?.store !== undefined || options.reasoning?.capture !== undefined
+          ? options.reasoning
+          : { capture: false, ...options.reasoning }
+        : { ...adopted, ...options.reasoning };
+  const reasoningHook: EffectReasoningHook = {
+    capable: options.provider.capabilities?.reasoning === true,
+    posture() {
+      const r = reasoningOf();
+      if (r?.capture === false) return "off";
+      return r?.store !== undefined ? "keeps" : "unconfigured";
+    },
+    adopt(defaults) {
+      adopted = defaults;
+    },
+  };
+  return new LlmEffect<TIn, TOut>(
+    async (input: TIn, ctx: EffectContext) => {
+      // The integrity check at the prompt boundary: tainted content is refused
+      // outside a `user` message and fenced inside one, and what comes back is
+      // plain strings — so no provider has to know taint exists.
+      const guarded = guardRequest(options.buildRequest(input, ctx), {
+        ...(options.maxInlineBytes !== undefined && { maxInlineBytes: options.maxInlineBytes }),
+        ...(options.maxInlineTotalBytes !== undefined && {
+          maxInlineTotalBytes: options.maxInlineTotalBytes,
+        }),
+      });
+      // R5 — fail closed on an undeclared modality BEFORE fetching any content or touching the
+      // network, then turn claim-check refs into bytes (live calls only).
+      assertRequestSupported(guarded, options.provider.capabilities);
+      const reasoningResolver = reasoningResolverOf(reasoningOf());
+      const request = await resolveRequestContent(guarded, options.resolveContent, {
+        ...(options.maxResolvedBytes !== undefined && { maxBytes: options.maxResolvedBytes }),
+        ...(ctx.signal !== undefined && { signal: ctx.signal }),
+        context: {
+          executionId: ctx.executionId,
+          workflowId: ctx.workflowId,
+          stepId: ctx.stepId,
+          ...(ctx.principal !== undefined && { principal: ctx.principal }),
+        },
+        // ADR 0133 D5 - reasoning text lives where capture put it, and is read back through an
+        // AUTHORIZING resolver (the ADR 0120 seam, origin "reasoning"): the configured one, else the
+        // sidecar read that serves a blob only to the execution it is sealed to.
+        ...(reasoningResolver !== undefined && { reasoningResolver }),
+      });
+      // K8.1 — forward the effect's cooperative-cancellation signal to the
+      // provider (unless buildRequest already set one), so a cancelled/timed-out
+      // execution severs the in-flight HTTP call instead of orphaning it.
+      if (request.signal === undefined && ctx.signal !== undefined) {
+        request.signal = ctx.signal;
+      }
+
+      // ONE durable outcome either way. The streamed path returns the assembled
+      // response, which the R8 conformance contract pins equal to what `complete`
+      // would have returned — so the journal shape does not depend on which path
+      // ran, and switching `stream` on cannot change what replay serves.
+      const reasoningSink = reasoningOf()?.onDelta;
+      const live =
+        reasoningOf()?.live === true && (ctx.onDelta !== undefined || reasoningSink !== undefined);
+      const raw = await (options.stream === true && options.provider.stream !== undefined
+        ? collectStream(options.provider.stream(request as LlmRequest), {
+            ...(ctx.signal !== undefined && { signal: ctx.signal }),
+            // ADR 0119 — the per-call sink (ctx.onDelta, set by a decider's scope) AND the
+            // configured one both fire; neither replaces the other. The per-call sink goes
+            // FIRST: it is the governed one, and a middleware delta guard severs the stream
+            // by THROWING from it — which must happen before any other tail sees the delta.
+            // Do not catch around it. The text is wrapped as untrusted content (ADR 0085).
+            // The configured sink is NOT called here under a runtime: ctx.onDelta is the
+            // guarded channel and the runtime forwards to `deltaSink` after the guards.
+            ...((options.onDelta !== undefined || ctx.onDelta !== undefined) && {
+              onDelta: (delta: string) => {
+                if (ctx.onDelta !== undefined) {
+                  ctx.onDelta({ delta: tainted(delta, `llm:${ctx.stepId}`) });
+                } else options.onDelta?.(delta, ctx);
+              },
+            }),
+            // ADR 0133 D6 - readable reasoning rides its own field on the governed per-call sink
+            // (so the runtime's delta guards see it, and a guard that throws severs the stream).
+            // Off unless `live`; never the configured `onDelta`, which is text-only.
+            ...(live && {
+              onReasoningDelta: (delta: string) => {
+                const reasoning = tainted(delta, `llm-reasoning:${ctx.stepId}`);
+                if (ctx.onDelta !== undefined) {
+                  ctx.onDelta({ delta: tainted("", `llm:${ctx.stepId}`), reasoning });
+                } else {
+                  try {
+                    reasoningSink?.(reasoning, ctx);
+                  } catch {
+                    // A live tail is a convenience: it cannot fail the model call (the durable record is D3).
+                  }
+                }
+              },
+            }),
+            ...(options.onToolDelta !== undefined && {
+              onToolDelta: (d: { id: string; name?: string; inputDelta: string }) =>
+                options.onToolDelta?.(d, ctx),
+            }),
+            ...(options.guard !== undefined && { guard: options.guard(ctx) }),
+          })
+        : options.provider.complete(request));
+      // ADR 0119 — hand the runtime the stream's end + usage. The runtime HOLDS this and
+      // sends the caller's terminal chunk only once the whole call has succeeded
+      // (middleware output phase and parse included), so `done` never precedes a failure.
+      // Streamed path only: a `complete` fallback delivered no deltas to terminate.
+      if (options.stream === true && options.provider.stream !== undefined) {
+        ctx.onDelta?.({
+          delta: tainted("", `llm:${ctx.stepId}`),
+          done: true,
+          ...(raw.usage !== undefined && { usage: raw.usage }),
+        });
+      }
+
+      // ADR 0133 D3 - readable reasoning is reduced to its recorded form BEFORE parse, so text
+      // never reaches a step value. A response with no reasoning is passed through untouched (G2).
+      // The same object goes through when there is none (callers compare responses by identity).
+      let response: LlmCapturedResponse = raw as LlmCapturedResponse;
+      if (raw.reasoning !== undefined) {
+        const { reasoning: returned, ...rest } = raw;
+        response =
+          returned.length > 0
+            ? { ...rest, reasoning: await captureReasoning(returned, reasoningOf(), ctx) }
+            : rest;
+      }
+      return parse(response, input);
+    },
+    // Wire pre-warm to the provider's own warm hook (connection/model cache),
+    // only when the provider implements one.
+    {
+      ...(options.provider.warm !== undefined && { warm: () => options.provider.warm?.() }),
+      // ADR 0133 D6 - the configured reasoning sink is reached through the runtime's governed pipe
+      // (delta guards first), only when the app turned live reasoning on.
+      reasoning: reasoningHook,
+      ...(options.reasoning?.onDelta !== undefined && {
+        reasoningSink: (delta: TaintedValue<string>, ctx: EffectContext) => {
+          if (reasoningOf()?.live === true) options.reasoning?.onDelta?.(delta, ctx);
+        },
+      }),
+      ...((options.onDelta !== undefined ||
+        options.onReset !== undefined ||
+        options.onToolReset !== undefined) && {
+        deltaSink: (chunk: EffectDelta, ctx: EffectContext) => {
+          if (chunk.reset === true) {
+            options.onReset?.(chunk.attempt ?? 2, ctx);
+            options.onToolReset?.(chunk.attempt ?? 2, ctx);
+          } else if (chunk.done !== true && chunk.reasoning === undefined) {
+            // A reasoning chunk (ADR 0133) is not text: the configured sink is text-only.
+            options.onDelta?.(unwrapTainted(chunk.delta), ctx);
+          }
+        },
+      }),
+    }
+  );
+}