Adds a before_builtins: ClassVar[bool] = False flag on StreamTransformer. When True, the mux registers the transformer ahead of the rest, preserving relative order within each lane.

Motivation

Content-mutating transformers — PII redaction, content filters, profanity scrubbers — need to run before built-in transformers like MessagesTransformer, which eagerly snapshots text fields (delta.text, delta.reasoning) into its projection. Today there's no way to register a transformer ahead of the built-ins, so any mutation a user transformer makes to delta.text lands too late: MessagesTransformer has already pushed the original string into the ChatModelStream text accumulator.

Motivating use case: PII redaction middleware in langchain (see langchain-ai/langchain#37591). Stream-level redaction wants to mutate delta.text before any consumer projection captures it. Without before_builtins, the only workable Python-side approach is wrap_model_call, which is heavier and only catches model output (not tool deltas, custom events, or subgraph outputs).

API

class _PIIRedactor(StreamTransformer):
    before_builtins: ClassVar[bool] = True

    def process(self, event):
        # mutate delta.text in place; MessagesTransformer sees the redacted string
        ...

The flag is a class attribute so transformers carry the placement decision with them — callers wiring middleware don't need to know whether the transformer needs pre-lane placement; the transformer itself declares it.

Ordering contract

Within each lane, the supplied order is preserved. The full registration order ends up as:

1. All before_builtins=True factories, in supplied order
2. All other factories, in supplied order
3. Pre-built transformers= instances, partitioned the same way

Built-ins keep the default before_builtins=False, so registration order is identical to before for anyone who hasn't opted in. No backwards-compatibility break.

Foot-gun (documented on the class)

Pre-lane transformers see tasks events before LifecycleTransformer and SubgraphTransformer consume them. Mutating event["params"]["namespace"] or the data dict's id / result / error / interrupts fields will desync their bookkeeping. Observe freely; mutate only fields no built-in reads.

The canonical safe mutation is delta.text (and delta.reasoning) on messages events — exactly the case content-filter transformers need.

Tests

tests/test_stream_before_builtins.py covers:

• Pre-lane factories register before others, and run first on dispatch
• Within-lane order is preserved
• A pre-lane redactor is registered before MessagesTransformer even when supplied second
• A pre-lane observer doesn't break LifecycleTransformer's bookkeeping (read-only observation is safe)
• Default is False on the base class and all built-ins
• End-to-end: a pre-lane redactor mutating delta.text results in the redacted string landing in MessagesTransformer's text accumulator — the actual proof that pre-lane placement does what it's supposed to do

Existing stream-transformer tests (test_stream_data_transformers, test_stream_messages_transformer, test_stream_lifecycle_transformer, test_stream_subgraph_transformer — 133 tests) all still pass.