reactor-runtime 3.2.4__tar.gz → 3.2.6__tar.gz

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.2.4
+Version: 3.2.6
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -18,7 +18,7 @@ Requires-Dist: numpy>=2.1
 Requires-Dist: prometheus-client>=0.26.0
 Requires-Dist: protobuf>=7.35.1
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: reactor-webrtc==0.12.0
+Requires-Dist: reactor-webrtc==0.14.0
 Requires-Dist: uvicorn>=0.49.0
 Requires-Python: >=3.12
 Project-URL: Source, https://github.com/reactor-team/reactor-runtime
@@ -44,6 +44,7 @@ Reactor Runtime turns an inference pipeline into a real-time, interactive media
 - 🎮 **Live interaction.** Clients send commands mid-generation: change a prompt, move a camera, adjust a parameter. The next frame reflects it.
 - 🔌 **No transport code.** You never import a WebRTC library, manage a WebSocket, or encode video. The runtime ships its own media engine as a wheel, so a plain Python container is all a model needs.
 - ✅ **Typed, validated commands.** Declare the commands your model accepts with standard Python types and constraints. The runtime validates every payload before your handler runs and compiles the surface into an OpenAPI schema that drives typed client SDKs.
+- 🔎 **Traceable logs.** `get_logger()` writes structured records — readable `key=value` in a terminal, JSON for a log pipeline. Every record a session writes carries that session's id automatically, so one filter recovers everything a single run logged.
 - 📦 **One container, anywhere.** The `reactor` CLI scaffolds a workspace, builds a small image, and runs it locally. The same image deploys to [Reactor](https://reactor.inc)'s GPU cloud unchanged.
 
 ## How it works
@@ -93,6 +94,18 @@ reactor run
 
 `reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
 
+Log from the same import, passing context as keyword arguments:
+
+```python
+from reactor_runtime import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("scene changed", prompt=self.prompt)
+```
+
+Records render as `key=value` text by default, or as one JSON object per line under `REACTOR_LOG_FORMAT=json`. While a session is live, its id is stamped on every record, so tracing one run's logs never requires threading an id through your call sites. Every record also carries the lifecycle phase it was written in, at both granularities: `state`, the session state machine's word, and `runtime_state`, the coarse word the health endpoint serves — so the logs of one phase — loading weights, a live session, teardown — are filterable by whichever vocabulary you are reading off another surface. The stamp is applied where records are written rather than where they are made, so a plain `logging.getLogger(__name__)` and the libraries your model imports are covered too.
+
 ## Install
 
 Everything runs through the [`reactor` CLI](https://docs.reactor.inc/deploy/platform/installation). There is nothing to install on your host but the CLI and Docker; the runtime ships inside the image the CLI builds for your workspace.

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/README.md

@@ -18,6 +18,7 @@ Reactor Runtime turns an inference pipeline into a real-time, interactive media
 - 🎮 **Live interaction.** Clients send commands mid-generation: change a prompt, move a camera, adjust a parameter. The next frame reflects it.
 - 🔌 **No transport code.** You never import a WebRTC library, manage a WebSocket, or encode video. The runtime ships its own media engine as a wheel, so a plain Python container is all a model needs.
 - ✅ **Typed, validated commands.** Declare the commands your model accepts with standard Python types and constraints. The runtime validates every payload before your handler runs and compiles the surface into an OpenAPI schema that drives typed client SDKs.
+- 🔎 **Traceable logs.** `get_logger()` writes structured records — readable `key=value` in a terminal, JSON for a log pipeline. Every record a session writes carries that session's id automatically, so one filter recovers everything a single run logged.
 - 📦 **One container, anywhere.** The `reactor` CLI scaffolds a workspace, builds a small image, and runs it locally. The same image deploys to [Reactor](https://reactor.inc)'s GPU cloud unchanged.
 
 ## How it works
@@ -67,6 +68,18 @@ reactor run
 
 `reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
 
+Log from the same import, passing context as keyword arguments:
+
+```python
+from reactor_runtime import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("scene changed", prompt=self.prompt)
+```
+
+Records render as `key=value` text by default, or as one JSON object per line under `REACTOR_LOG_FORMAT=json`. While a session is live, its id is stamped on every record, so tracing one run's logs never requires threading an id through your call sites. Every record also carries the lifecycle phase it was written in, at both granularities: `state`, the session state machine's word, and `runtime_state`, the coarse word the health endpoint serves — so the logs of one phase — loading weights, a live session, teardown — are filterable by whichever vocabulary you are reading off another surface. The stamp is applied where records are written rather than where they are made, so a plain `logging.getLogger(__name__)` and the libraries your model imports are covered too.
+
 ## Install
 
 Everything runs through the [`reactor` CLI](https://docs.reactor.inc/deploy/platform/installation). There is nothing to install on your host but the CLI and Docker; the runtime ships inside the image the CLI builds for your workspace.

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/pyproject.toml

@@ -92,7 +92,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.2.4"
+version = "3.2.6"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -115,7 +115,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.12.0",
+    "reactor-webrtc==0.14.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.2.4"
+version = "3.2.6"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,7 +41,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.12.0",
+    "reactor-webrtc==0.14.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/__init__.py

@@ -49,6 +49,7 @@ from reactor_runtime.interface import (
     session_ended,
     session_started,
 )
+from reactor_runtime.log import get_logger
 from reactor_runtime.paths import get_weights_path
 
 __version__ = version("reactor-runtime")
@@ -89,6 +90,7 @@ __all__ = [
     "disconnected",
     "event",
     "file_uploaded",
+    "get_logger",
     "get_weights_path",
     "session_ended",
     "session_started",

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/core/model.py

@@ -238,10 +238,16 @@ class SessionEnded(ReactorEvent):
     Attributes:
         session_id: Identifier for the session that ended.
         reason: Why the session ended.
+        _log_binding: The log session binding to retire once the
+            ``@session_ended`` hook has run. Internal plumbing between the
+            runner and the reactor loop, never surfaced to a hook: dispatch is
+            what proves the hook's records were written while the binding was
+            live, so dispatch is where it is released.
     """
 
     session_id: str
     reason: EndReason
+    _log_binding: int = 0
 
 
 @dataclass(frozen=True)

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/core/session.py

@@ -69,6 +69,12 @@ class SessionEvent(Enum):
     ``CLOSING``, and carries an :class:`~reactor_runtime.core.model.EndReason`
     in ``detail.reason`` (and, for a crash, the error) so a consumer learns why.
 
+    ``INITIALIZING`` records that the runtime is still loading its weights. It is
+    a self-loop legal only in ``CREATED``, emitted once at boot before the load
+    blocks, so a consumer replaying the journal observes the loading phase — the
+    one phase otherwise silent, since the runner emits nothing until it leaves
+    ``CREATED`` on ``INITIALIZATION_SUCCESS``.
+
     ``CHUNK_READY``, ``CLIP_READY``, ``COMMAND``, ``ERROR``, and ``METRIC`` are
     the journal-only events (:data:`JOURNAL_EVENTS`): facts recorded for an
     external consumer rather than moves of the lifecycle. Each is a pure
@@ -81,6 +87,7 @@ class SessionEvent(Enum):
 
     INITIALIZATION_SUCCESS = auto()
     INITIALIZATION_FAIL = auto()
+    INITIALIZING = auto()
     START_SESSION = auto()
     STOP_SESSION = auto()
     TIMEOUT = auto()

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/interface/model/reactor_model.py

@@ -43,7 +43,7 @@ from reactor_runtime.interface.internal.reactor_core import (
     RequestId,
 )
 from reactor_runtime.interface.model.contract import ModelContract
-from reactor_runtime.log import get_logger
+from reactor_runtime.log import get_logger, release_session_id
 
 logger = get_logger(__name__)
 
@@ -188,6 +188,10 @@ class ReactorModel(ReactorCore):
             self._set_connected(0)
             await self._invoke_hook(hooks.session_ended, None)
             self._clients.clear()
+            # The hook has returned, so its records were written while the
+            # session's log binding was live; the session's last ambient writer
+            # is done and the binding retires here, on the model thread.
+            release_session_id(event._log_binding)
         elif isinstance(event, FileUploaded):
             await self._invoke_hook(hooks.file_uploaded, event.conn_id, uploaded_file=event.file)
 

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/log.py

@@ -8,10 +8,25 @@ of two shapes, chosen by the ``REACTOR_LOG_FORMAT`` environment variable:
 - ``json``: one JSON object per line, ready for a log pipeline to parse.
 
 Call sites pass structured context as keyword arguments —
-``log.info("session started", session_id=sid)`` — and the active formatter
-renders them; the wire shape is the formatter's concern, not the call site's.
+``log.info("chunk encoded", chunk_idx=idx)`` — and the active formatter renders
+them; the wire shape is the formatter's concern, not the call site's.
 ``configure`` installs the chosen formatter on the root logger, and
 ``get_logger`` returns a logger to write through.
+
+Three fields arrive without a call site naming them, stamped by
+:class:`SessionContextFilter` on the handler ``configure`` installs. While a
+session is live, every record carries its ``session_id``. From the moment the
+runtime boots, every record carries the lifecycle it was written in, at both
+granularities: ``state``, the session state machine's word — the same words the
+session descriptor's ``state`` field serves — and ``runtime_state``, its coarse
+projection, the words the health route serves (``loading`` / ``available`` /
+``serving`` / ``terminated``). Carrying both means a reader can filter by
+whichever vocabulary they read off a surface: the model-load window is
+``state="created"`` and equally ``runtime_state="loading"``. Because the stamp
+happens where records are written rather than where they are made, it reaches a
+model's own ``logging.getLogger(__name__)`` and any third-party library that
+propagates to root, so a line can be traced to the session and phase that
+produced it without model code threading any of it through its call sites.
 """
 
 from __future__ import annotations
@@ -35,6 +50,94 @@ _JSON_RESERVED = frozenset({"ts", "level", "logger", "msg", "exc_info"})
 
 _QUOTE_TRIGGERS = (" ", "=", '"', "\n", "\r", "\t")
 
+# The live session's id, stamped on every record while it is set. A module global
+# rather than a ContextVar because a session fans its work across plain worker
+# threads, which do not inherit context; the runtime hosts one session at a time,
+# so a single value is unambiguous.
+_session_id: str | None = None
+
+# Counts bindings, so a release can name the one it retires. Two sessions may
+# carry the same id — nothing stops a caller reusing one — and a release that
+# matched on the id alone would unbind the session that reused it.
+_session_binding = 0
+
+
+def set_session_id(session_id: str | None) -> int:
+    """Stamp *session_id* on every record written from now on.
+
+    Args:
+        session_id: The live session's id, or ``None`` to stamp nothing.
+
+    Returns:
+        A token naming this binding, which :func:`release_session_id` takes to
+        retire it.
+    """
+    global _session_id, _session_binding
+    _session_id = session_id
+    _session_binding += 1
+    return _session_binding
+
+
+def clear_session_id() -> None:
+    """Stop stamping a session id, for the window between sessions."""
+    set_session_id(None)
+
+
+def release_session_id(binding: int) -> None:
+    """Retire the binding *binding* names, leaving a later one in place.
+
+    A session's teardown outlives the move that ends it, so the release that
+    follows one is deferred until that work has finished. By then the next
+    session may already have bound its own id — the same id, even, since nothing
+    stops a caller reusing one — so a release names the binding it retires rather
+    than the value that binding held.
+
+    Args:
+        binding: The token :func:`set_session_id` returned, ignored once a later
+            binding has replaced the one it names.
+    """
+    global _session_id
+    if _session_binding == binding:
+        _session_id = None
+
+
+def get_session_id() -> str | None:
+    """Return the id currently being stamped, or ``None`` between sessions."""
+    return _session_id
+
+
+# The runtime's lifecycle, stamped on every record while set: the state
+# machine's own word and its coarse projection. One fact at two granularities,
+# so one setter binds both and they cannot drift apart. Unlike the session id
+# they need no binding token: there is always exactly one current state and the
+# latest write is by definition the truth, so last-write-wins is the correct
+# semantics rather than a race to guard against.
+_state: str | None = None
+_runtime_state: str | None = None
+
+
+def set_state(state: str | None, runtime_state: str | None) -> None:
+    """Stamp *state* and *runtime_state* on every record written from now on.
+
+    Args:
+        state: The session state machine's word, or ``None`` to stamp nothing.
+        runtime_state: Its coarse lifecycle projection, the health route's
+            vocabulary, or ``None`` to stamp nothing.
+    """
+    global _state, _runtime_state
+    _state = state
+    _runtime_state = runtime_state
+
+
+def get_state() -> str | None:
+    """Return the machine word currently being stamped, or ``None`` before boot."""
+    return _state
+
+
+def get_runtime_state() -> str | None:
+    """Return the coarse word currently being stamped, or ``None`` before boot."""
+    return _runtime_state
+
 
 def _logfmt_value(value: Any) -> str:
     """Render *value* as a logfmt-safe token.
@@ -63,6 +166,37 @@ def _record_fields(record: logging.LogRecord) -> dict[str, Any]:
     return {key: value for key, value in raw.items() if value is not None}
 
 
+class SessionContextFilter(logging.Filter):
+    """Stamp the live session's id and the runtime's state on every record.
+
+    Sits on the handler rather than on one logger, so it sees every record a
+    handler writes: the runtime's own, a model's ``logging.getLogger(__name__)``,
+    and a third-party library's that propagates to root. A call site that names
+    ``session_id``, ``state``, or ``runtime_state`` itself keeps its own value —
+    a model logging its own ``state`` claims that record's field, deliberately —
+    and a field with nothing bound, the session id between sessions or the
+    states before boot, is absent rather than empty.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Merge the ambient context into *record*'s structured fields."""
+        stamped = {
+            "session_id": _session_id,
+            "state": _state,
+            "runtime_state": _runtime_state,
+        }
+        context = {key: value for key, value in stamped.items() if value is not None}
+        if not context:
+            return True
+        fields = getattr(record, _REACTOR_FIELDS_ATTR, None)
+        if not isinstance(fields, dict):
+            setattr(record, _REACTOR_FIELDS_ATTR, context)
+            return True
+        for key, value in context.items():
+            fields.setdefault(key, value)
+        return True
+
+
 class TextFormatter(logging.Formatter):
     """Render a record as its message followed by ``key=value`` field tokens."""
 
@@ -159,7 +293,9 @@ def configure(*, level: int = logging.INFO, stream: IO[str] | None = None) -> No
     The shape is chosen by ``REACTOR_LOG_FORMAT``: ``json`` for one JSON object
     per line, anything else (the default) for human-readable ``key=value`` text.
     Replaces any handlers already on the root logger so output has a single,
-    predictable shape.
+    predictable shape. The handler carries a :class:`SessionContextFilter`, so
+    every record written through it is stamped with the live session's id and
+    the runtime's lifecycle state at both granularities.
 
     Args:
         level: The level the root logger is set to.
@@ -171,6 +307,7 @@ def configure(*, level: int = logging.INFO, stream: IO[str] | None = None) -> No
     )
     handler = logging.StreamHandler(stream)
     handler.setFormatter(formatter)
+    handler.addFilter(SessionContextFilter())
     root = logging.getLogger()
     for existing in root.handlers[:]:
         root.removeHandler(existing)
@@ -180,8 +317,16 @@ def configure(*, level: int = logging.INFO, stream: IO[str] | None = None) -> No
 
 __all__ = [
     "JsonFormatter",
+    "SessionContextFilter",
     "StructuredLogger",
     "TextFormatter",
+    "clear_session_id",
     "configure",
     "get_logger",
+    "get_runtime_state",
+    "get_session_id",
+    "get_state",
+    "release_session_id",
+    "set_session_id",
+    "set_state",
 ]

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/recording/recorder.py

@@ -369,7 +369,10 @@ class Recorder:
             try:
                 (self._session_dir / _COMPLETE_MARKER).write_text("")
             except OSError:
-                logger.exception("failed to write recording completion marker")
+                logger.exception(
+                    "failed to write recording completion marker",
+                    session_id=self._session_id,
+                )
         self._fire_ready_chunks()
         self._fire_ready_clips()
         self._watch_stop.set()
@@ -378,9 +381,15 @@ class Recorder:
         if watch_thread is not None:
             watch_thread.join(timeout=2.0)
         self._started = False
+        # session_id is named explicitly, like the start's: the recorder outlives
+        # the session's ambient log context, which the model retires at its own
+        # session-ended dispatch, so a record written on the way out — this one,
+        # the marker and callback failures, the feed thread's exit — attributes
+        # itself.
         logger.info(
             "recorder stopped",
             recording_id=self._session_id,
+            session_id=self._session_id,
             dropped=self._dropped_frames,
         )
 
@@ -651,7 +660,10 @@ class Recorder:
                 if self._has_audio and audio is not None:
                     encoder.feed_audio(audio)
             except Exception:
-                logger.exception("recorder encoder feed failed; disabling recording")
+                logger.exception(
+                    "recorder encoder feed failed; disabling recording",
+                    session_id=self._session_id,
+                )
                 self._disabled = True
                 self._drain_feed_queue()
                 return
@@ -812,7 +824,7 @@ class Recorder:
             try:
                 callback(clip)
             except Exception:
-                logger.exception("clip-ready callback raised")
+                logger.exception("clip-ready callback raised", session_id=self._session_id)
 
     def _fire_ready_chunks(self) -> None:
         """Announce every recording segment that has closed since the last poll.
@@ -839,7 +851,7 @@ class Recorder:
             try:
                 callback(recording_id, idx)
             except Exception:
-                logger.exception("chunk-ready callback raised")
+                logger.exception("chunk-ready callback raised", session_id=recording_id)
 
     # -- HTTP serving ---------------------------------------------------------
 

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/runner/runner.py

@@ -54,7 +54,7 @@ from reactor_runtime.interface.events.messages import ModelMessage
 from reactor_runtime.interface.internal.bridge import ModelBridge
 from reactor_runtime.interface.internal.reactor_core import MediaOps
 from reactor_runtime.interface.model.contract import ModelContract
-from reactor_runtime.log import get_logger
+from reactor_runtime.log import get_logger, set_session_id, set_state
 from reactor_runtime.manifest import import_model_class
 from reactor_runtime.message_gateway import InboundCommand, MessageGateway
 from reactor_runtime.metrics import (
@@ -98,6 +98,17 @@ _RUNTIME_STATES: dict[SessionState, RuntimeState] = {
     SessionState.TERMINATED: RuntimeState.TERMINATED,
 }
 
+
+def _stamp_log_state(state: SessionState) -> None:
+    """Bind the log's state context to *state*, at both granularities.
+
+    Records carry the machine's own word and the coarse word the health route
+    serves, so a reader can filter by whichever vocabulary the surface they are
+    looking at showed them.
+    """
+    set_state(state.name.lower(), _RUNTIME_STATES[state].value)
+
+
 # How long to wait for an upload's bytes to arrive when a command or notification
 # references it before they are written. A client references an upload over the
 # data channel while its bytes are still being delivered on a separate request,
@@ -169,6 +180,10 @@ class Runner(ServiceComponent, ConnectionSink):
         self._cfg = cfg
         self._metrics = metrics or RuntimeMetrics(version=_server_version(), model=cfg.model_ref)
         self._sm = SessionStateMachine()
+        # The log's state context starts at the machine's starting state, so the
+        # model-load window — records written before any transition — is already
+        # stamped; every later move re-stamps in _dispatch_transition.
+        _stamp_log_state(self._sm.current_state)
         self._sm.on_transition(self._dispatch_transition)
         # The session surface of the metrics is one listener over the same moves
         # the journal carries, so no session code below calls an instrument.
@@ -206,12 +221,18 @@ class Runner(ServiceComponent, ConnectionSink):
         self._teardown: set[asyncio.Task[None]] = set()
         self._orphan_task: asyncio.Task[None] | None = None
         self._session_id = SESSION_ID
-        # The id a recording is stored and addressed under, set per session in
-        # start_session. Separate from the fixed transport session id so a director
-        # can align a recording with the platform's session id; a session started
-        # without one mints a fresh id, so sequential recordings in a reused process
-        # never share a directory. The construction value is an unused placeholder.
+        # The session's own id, set per session in start_session: the id a
+        # recording is stored and addressed under, and the id stamped on the
+        # session's log records. Separate from the fixed transport session id so a
+        # caller can align both with the id it knows the session by; a session
+        # started without one mints a fresh id, so sequential recordings in a
+        # reused process never share a directory and the logs of one session are
+        # never read as another's. The construction value is an unused placeholder.
         self._recording_id = SESSION_ID
+        # Names the log's current session binding, so the release that follows a
+        # session retires that binding and not a later session's. Zero until the
+        # first session binds one.
+        self._log_binding = 0
         self._accepting = True
         # The process-shutdown hook, wired by the assembly so the runner can ask
         # the service to bring the process down when the session is terminated
@@ -237,11 +258,17 @@ class Runner(ServiceComponent, ConnectionSink):
 
         The model load runs off the event loop (it may block while it reads
         weights), so the HTTP surface — already up by the time this runs — stays
-        responsive throughout, and a client subscribed to ``/events`` observes
-        the ``initialization_success``/``initialization_fail`` transition live.
+        responsive throughout: a client subscribed to ``/events`` observes the
+        ``initializing`` self-loop journalled before the load, then the
+        ``initialization_success``/``initialization_fail`` transition when it ends.
         """
         self._loop = asyncio.get_running_loop()
         logger.info("loading model", model=self._cfg.model_ref)
+        # Journal the loading phase before the (blocking) load, so a consumer
+        # replaying /events sees the runtime is initializing during the load
+        # window rather than nothing until READY. A self-loop on CREATED: no
+        # state change, no side effect (the bridge is not built yet).
+        self._sm.send(SessionEvent.INITIALIZING)
         started_at = time.monotonic()
         try:
             model_cls = import_model_class(self._cfg.model_ref)
@@ -580,11 +607,12 @@ class Runner(ServiceComponent, ConnectionSink):
         The rejection surfaces the current state so the caller can report the
         precise reason. The parameters seed the session's initial state.
 
-        A ``session_id`` in *params* is adopted as the id this session's recording
-        is stored and addressed under, so a director can align clips with the
-        platform's session id; absent one, a fresh id is minted per session so
-        sequential recordings never overwrite each other. The transport session id
-        is unaffected — it is always :data:`SESSION_ID`.
+        A ``session_id`` in *params* is adopted as this session's own id: the id
+        its recording is stored and addressed under, and the id stamped on every
+        log record the session writes. A caller can therefore align both clips and
+        logs with the id it knows the session by. Absent one, a fresh id is minted
+        per session so sequential recordings never overwrite each other. The
+        transport session id is unaffected — it is always :data:`SESSION_ID`.
 
         Args:
             params: The initial session parameters supplied by the caller.
@@ -1078,11 +1106,27 @@ class Runner(ServiceComponent, ConnectionSink):
         declare a dead model ready again. Real moves log at info; journal
         self-loops log at debug so a per-segment ``chunk_ready`` does not flood
         the log.
+
+        The session boundary is also where the log's session context binds, so
+        every record written while a session is live names it, the opening move
+        included. The release travels differently: it rides the ``SessionEnded``
+        event into the model, whose dispatch retires the binding once the
+        ``@session_ended`` hook has returned. A terminal move dispatches no
+        ``SessionEnded`` and releases nothing — the process is exiting, and its
+        last records belong to the session that brought it down. The log's state
+        context re-stamps here too, before the move's own line, so a record
+        reads the state the process was in when it was written.
         """
+        if transition.is_session_start:
+            self._log_binding = set_session_id(self._recording_id)
+        if transition.from_state is not transition.to_state:
+            _stamp_log_state(transition.to_state)
         log = logger.debug if transition.event in JOURNAL_EVENTS else logger.info
+        # The fixed transport id (SESSION_ID) is deliberately not a field here:
+        # one constant value per process carries nothing, and squatting on
+        # session_id would mask the id the session is known by.
         log(
             "session transition",
-            session_id=self._session_id,
             event=transition.event.name.lower(),
             from_state=transition.from_state.name.lower(),
             to_state=transition.to_state.name.lower(),
@@ -1138,7 +1182,12 @@ class Runner(ServiceComponent, ConnectionSink):
             bridge.dispatch_reactor_event(SessionStarted(self._session_id))
         if transition.is_session_end:
             reason = transition.detail.get("reason", EndReason.STOPPED)
-            bridge.dispatch_reactor_event(SessionEnded(self._session_id, reason))
+            bridge.dispatch_reactor_event(
+                # The event carries the log binding so its dispatch — the point
+                # where the @session_ended hook has provably returned — is what
+                # retires it, on the model thread.
+                SessionEnded(self._session_id, reason, self._log_binding)
+            )
         if transition.event is SessionEvent.CONNECTION_OPENED:
             bridge.dispatch_reactor_event(
                 ClientConnected(transition.detail["conn_id"], self._connections.count)

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/runner/state_machine.py

@@ -42,6 +42,11 @@ from reactor_runtime.core import JOURNAL_EVENTS, SessionEvent, SessionState, Tra
 _TRANSITIONS: dict[SessionEvent, dict[SessionState, SessionState]] = {
     SessionEvent.INITIALIZATION_SUCCESS: {SessionState.CREATED: SessionState.READY},
     SessionEvent.INITIALIZATION_FAIL: {SessionState.CREATED: SessionState.TERMINATED},
+    # INITIALIZING is the runtime's "still loading" fact: a self-loop legal only
+    # in CREATED, emitted once at boot so a journal consumer sees the loading
+    # phase that is otherwise silent until INITIALIZATION_SUCCESS leaves CREATED.
+    # It changes no state and leaves the connection count alone (see _update_count).
+    SessionEvent.INITIALIZING: {SessionState.CREATED: SessionState.CREATED},
     SessionEvent.START_SESSION: {SessionState.READY: SessionState.WAITING},
     SessionEvent.STOP_SESSION: {
         SessionState.STREAMING: SessionState.CLOSING,

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/serve.py

@@ -8,8 +8,9 @@ platform.
 
 This is also the runtime's one configuration boundary: the manifest names the
 model, and the surrounding deployment names everything else (bind address, the
-ICE servers and port range, the congestion-control bitrate limits, the video
-codec preference order, the lifecycle timeouts) through environment variables.
+ICE servers and port range, the congestion-control and per-sender bitrate
+limits, the video codec preference order, the lifecycle timeouts) through
+environment variables.
 The transport and lifecycle config objects stay free of environment reads; the
 small adapter here is the only place that translates the outside world into
 them.
@@ -26,7 +27,7 @@ import sys
 from pathlib import Path
 
 from reactor_runtime import log
-from reactor_runtime.core import RuntimeConfig
+from reactor_runtime.core import RuntimeConfig, RuntimeState, SessionState
 from reactor_runtime.http import HttpServer
 from reactor_runtime.manifest import MANIFEST, load_config
 from reactor_runtime.metrics import RuntimeMetrics
@@ -200,6 +201,32 @@ def _bwe_limits_from_env() -> tuple[int, int, int]:
     return min_kbps, max_kbps, initial_kbps
 
 
+def _sender_limits_from_env() -> tuple[int, int]:
+    """Read the per-sender bitrate bounds, checked at boot like the BWE ones.
+
+    These bound one track's encoder, where the BWE limits bound the whole
+    connection's estimate. Both must allow a rate for a stream to reach it, and
+    the per-sender ceiling is the one that lifts libwebrtc's resolution-keyed
+    default of 2500 kbps.
+
+    ``0`` or less means "leave this bound at the libwebrtc default", matching how
+    the rest of this config spells an absent limit. A negative is not an error
+    here for that reason, but ``min`` above ``max`` is: libwebrtc refuses the
+    pair, and finding out at boot beats finding out on every negotiation.
+
+    Raises:
+        SystemExit: If the ordering does not hold.
+    """
+    max_kbps = _int_env("WEBRTC_SENDER_MAX_KBPS", WebRtcConfig.sender_max_kbps)
+    min_kbps = _int_env("WEBRTC_SENDER_MIN_KBPS", WebRtcConfig.sender_min_kbps)
+    if min_kbps > 0 < max_kbps and min_kbps > max_kbps:
+        raise SystemExit(
+            "WEBRTC_SENDER_MIN_KBPS must not exceed WEBRTC_SENDER_MAX_KBPS; "
+            f"got {min_kbps} > {max_kbps}"
+        )
+    return max_kbps, min_kbps
+
+
 def _webrtc_config_from_env() -> WebRtcConfig:
     """Build the WebRTC transport config from the environment.
 
@@ -207,6 +234,7 @@ def _webrtc_config_from_env() -> WebRtcConfig:
     single place the outside world is translated into it.
     """
     bwe_min_kbps, bwe_max_kbps, bwe_initial_kbps = _bwe_limits_from_env()
+    sender_max_kbps, sender_min_kbps = _sender_limits_from_env()
     return WebRtcConfig(
         ice_servers=_ice_servers_from_env(),
         port_range=_port_range_from_env(),
@@ -216,6 +244,8 @@ def _webrtc_config_from_env() -> WebRtcConfig:
         bwe_min_kbps=bwe_min_kbps,
         bwe_max_kbps=bwe_max_kbps,
         bwe_initial_kbps=bwe_initial_kbps,
+        sender_max_kbps=sender_max_kbps,
+        sender_min_kbps=sender_min_kbps,
     )
 
 
@@ -342,6 +372,12 @@ def main() -> None:
     from reactor_runtime.transport.webrtc.peer import libwebrtc_peer_factory
 
     log.configure(level=_log_level_from_env())
+    # The runner re-stamps this at construction and on every move; stamping here
+    # too covers the lines written before it exists — the process is up and the
+    # model is not loaded, which is exactly what CREATED names and what LOADING
+    # projects it to — so every record the process writes carries its lifecycle,
+    # the first one included.
+    log.set_state(SessionState.CREATED.name.lower(), RuntimeState.LOADING.value)
     manifest = Path.cwd() / MANIFEST
     if not manifest.is_file():
         raise SystemExit(f"no {MANIFEST} found in {Path.cwd()}")

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/transport/webrtc/config.py

@@ -97,6 +97,22 @@ class WebRtcConfig:
         bwe_initial_kbps: Starting bitrate before estimates arrive.
         bwe_target_update_threshold: Relative change below which a new bitrate
             estimate is ignored rather than re-applied to the encoders.
+        sender_max_kbps: Ceiling for each sendonly *video* track's own encoder,
+            which is
+            a different limit from ``bwe_max_kbps`` and the one that actually
+            caps a video stream. The two are conjunctive — the lower wins — and
+            without this a sender's maximum comes from libwebrtc's
+            resolution-keyed default, which is 2500 kbps for anything above
+            960x540. Every frame size we send at 720p or larger would cap at
+            2.5 Mbps no matter how much headroom the estimate had. Audio senders
+            are left alone: that default is keyed on frame size, so there is no
+            equivalent for them to clear. ``0`` or less leaves the libwebrtc
+            default in place.
+        sender_min_kbps: Floor for each sendonly video track's own encoder. ``0`` or
+            less leaves it unset, which is the default: a floor stops the
+            encoder degrading gracefully, so on a link that cannot sustain it
+            the trade is lower quality for packet loss. Useful mainly when
+            several tracks compete and one must be preserved.
         rtx_max_size_packets: Retransmission history depth, in packets.
         rtx_max_size_time_ms: Retransmission history depth, in milliseconds;
             ``0`` means no time limit.
@@ -134,6 +150,8 @@ class WebRtcConfig:
     bwe_max_kbps: int = 10000
     bwe_initial_kbps: int = 4000
     bwe_target_update_threshold: float = 0.05
+    sender_max_kbps: int = 10000
+    sender_min_kbps: int = 0
     rtx_max_size_packets: int = 512
     rtx_max_size_time_ms: int = 200
     rtp_payload_mtu: int = 1200

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/transport/webrtc/peer.py

@@ -17,8 +17,8 @@ garble.
 Per-peer audio isolation
 ------------------------
 Each outbound audio track is created with
-``PeerConnectionFactory.create_audio_track_with_local_source()``, which backs the
-track with a ``LocalAudioSource`` — a custom ``AudioSourceInterface`` that
+``PeerConnectionFactory.create_audio_track_with_options(source=LocalPush)``,
+which backs the track with a ``LocalAudioSource`` — a custom ``AudioSourceInterface`` that
 maintains the list of sinks registered by each peer connection's voice send
 channel.  When ``track.push_pcm()`` is called, it delivers PCM directly to that
 track's encoder via ``AudioTrackSinkInterface::OnData``, bypassing the shared
@@ -272,6 +272,36 @@ async def _apply_bitrate_limits(pc: rw.PeerConnection, config: WebRtcConfig) ->
     )
 
 
+async def _apply_sender_bitrate(transceiver: rw.Transceiver, config: WebRtcConfig) -> None:
+    """Apply the configured per-sender bitrate bounds to one sendonly video transceiver.
+
+    A different limit from ``_apply_bitrate_limits``: that one bounds the whole
+    connection's congestion-control estimate, this one bounds what a single
+    track's encoder may spend of it. They are conjunctive, so a stream runs fast
+    only when both allow it — and this is the one that has to be raised, because
+    with nothing set libwebrtc derives a sender's ceiling from the frame size
+    alone and it is 2500 kbps for anything above 960x540.
+
+    **Video only**, for two reasons that agree. The default being lifted is
+    ``GetMaxDefaultVideoBitrateKbps``, keyed on frame size, so there is no
+    equivalent for an audio sender to clear — the config's 10 Mbps ceiling would
+    say nothing to a 64 kbps Opus stream. (The bounds themselves do apply to
+    audio and would cap its allocation; we simply have no reason to.) And an
+    audio transceiver materialised from a remote offer has no encodings to write
+    until the answer is applied, where a video one has them as soon as the
+    transceiver exists, so calling this here would fail on every audio track.
+
+    ``0`` or less in the config leaves that bound at the libwebrtc default, which
+    is how the rest of this config spells an absent limit; the binding takes
+    ``None`` for it. Applied per negotiation, since every offer rebuilds the peer
+    and its transceivers come up on library defaults.
+    """
+    await transceiver.set_send_bitrate(
+        min_bps=config.sender_min_kbps * 1000 if config.sender_min_kbps > 0 else None,
+        max_bps=config.sender_max_kbps * 1000 if config.sender_max_kbps > 0 else None,
+    )
+
+
 def _is_terminal_state(state: rw.PeerConnectionState) -> bool:
     """Return whether a peer-connection state means the wire is gone.
 
@@ -513,9 +543,16 @@ class WebRTCPeer:
                 if info.kind is TrackKind.VIDEO:
                     track = factory.create_video_track(info.name)
                 else:
-                    track = factory.create_audio_track_with_local_source(info.name)
+                    # LocalPush, not the factory ADM: each outbound audio track
+                    # gets its own source, so one peer's audio cannot reach
+                    # another's encoder. See the module docstring.
+                    track = factory.create_audio_track_with_options(
+                        info.name, source=rw.AudioTrackSource.LocalPush
+                    )
                 await transceiver.set_track(track)
                 await transceiver.set_direction(rw.TransceiverDirection.SendOnly)
+                if info.kind is TrackKind.VIDEO:
+                    await _apply_sender_bitrate(transceiver, self._config)
                 self._out_tracks[info.name] = track
             if codec_preferences and transceiver.kind() == rw.MediaKind.Video:
                 await transceiver.set_codec_preferences(codec_preferences)
@@ -873,7 +910,11 @@ class WebRTCPeer:
             logger.debug("data-channel send failed", exc_info=True)
 
     async def add_ice(self, candidate: IceCandidate) -> None:
-        """Add a trickle-ICE candidate; valid before and after the wire connects."""
+        """Add a trickle-ICE candidate; valid before and after the wire connects.
+
+        An empty candidate string is the end-of-candidates marker (RFC 8838);
+        the native binding accepts it as a no-op.
+        """
         pc = self._pc
         if self._stop_event.is_set() or pc is None:
             return
@@ -1003,6 +1044,8 @@ class WebRTCPeer:
                 if info.name in paused
                 else rw.TransceiverDirection.SendOnly
             )
+            if info.kind is TrackKind.VIDEO:
+                await _apply_sender_bitrate(transceiver, self._config)
 
     # =========================================================================
     # Seam: stats and teardown

{reactor_runtime-3.2.4 → reactor_runtime-3.2.6}/src/reactor_runtime/transport/webrtc/signaling.py

@@ -46,7 +46,8 @@ class IceCandidate:
     """One trickle-ICE candidate from the client.
 
     Attributes:
-        candidate: The candidate string (SDP ``a=candidate`` form).
+        candidate: The candidate string (SDP ``a=candidate`` form); an empty
+            string is the end-of-candidates marker (RFC 8838).
         sdp_mid: The media-stream identifier the candidate belongs to, or
             ``None`` when addressed by m-line index instead.
         sdp_mline_index: The index of the m-line the candidate belongs to, or