feat: add trace export

README.md

@@ -33,3 +33,9 @@ The default model string includes the provider suffix used by Hugging Face Infer
 Configure the token as a Hugging Face Space secret named `HF_TOKEN`. `HUGGINGFACEHUB_API_TOKEN` is also supported. Do not commit tokens to the repository, README, app code, logs, or trace output.
 
 Local deterministic mode and app launch work without `HF_TOKEN`.
+
+## Trace export
+
+Use the collapsed **Trace / Debug** panel to inspect a readable JSON preview of the current show trace. After creating a show, the **Download Trace JSON** button saves a file named `ai-puppet-theater-trace-<session_id>.json`.
+
+The trace includes session metadata, the premise, title, setting, selected actor and Director backends, model ids when used, Director decisions, actor responses, audience actions, validation status, latency, and fallback metadata. Trace output is sanitized for sharing: it does not include Hugging Face tokens, environment variable values, private local paths, raw tracebacks, actor secrets, or hidden reasoning.

app.py

@@ -16,6 +16,7 @@ from puppet_theater import (
     throw_prop,
     warm_up_openbmb,
 )
+from puppet_theater.trace import add_trace_event, render_trace_json, write_trace_json_file
 
 
 EMPTY_STAGE = """
@@ -1598,9 +1599,7 @@ def render_director_log(session: TheaterSession | None) -> str:
 
 
 def render_trace(session: TheaterSession | None) -> str:
-    if session is None:
-        return EMPTY_TRACE
-    return "\n".join(f"- {entry}" for entry in session.trace_events)
+    return render_trace_json(session)
 
 
 def normalize_backend_name(backend_name: str | None) -> str:
@@ -1700,6 +1699,7 @@ def render_outputs(session: TheaterSession | None):
         render_transcript(session),
         render_director_log(session),
         render_trace(session),
+        write_trace_json_file(session),
         render_backend_settings(session),
     )
 
@@ -1724,6 +1724,7 @@ def create_show(
             "No premise yet. Add a premise to raise the curtain.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(
                 None,
                 selected_backend,
@@ -1760,6 +1761,7 @@ def reset_show():
         EMPTY_TRANSCRIPT,
         EMPTY_DIRECTOR_LOG,
         EMPTY_TRACE,
+        None,
         "deterministic",
         "deterministic",
         DEFAULT_MAX_NEW_TOKENS,
@@ -1783,6 +1785,7 @@ def advance_one_beat(
             "Create a show before running a beat.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
@@ -1806,6 +1809,7 @@ def advance_full_act(
             "Create a show before running the full act.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
         return
@@ -1821,7 +1825,14 @@ def advance_full_act(
         session.director_log.append(
             "OpenBMB is selected, so Run Full Act will use deterministic playback for this run."
         )
-        session.trace_events.append("full_act_openbmb_deterministic_playback")
+        add_trace_event(
+            session,
+            "full_act_deterministic_playback",
+            backend_name=selected_backend,
+            director_mode=selected_director_mode,
+            fallback_used=True,
+            fallback_reason="OpenBMB full-act playback uses deterministic mode to keep the demo responsive.",
+        )
 
     if session.beat_index >= session.max_beats:
         if deterministic_full_act:
@@ -1862,6 +1873,7 @@ def throw_audience_prop(
             "Create a show before throwing a prop.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
@@ -1885,6 +1897,7 @@ def summon_audience_actor(
             "Create a show before summoning an actor.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
@@ -1907,6 +1920,7 @@ def request_audience_finale(
             "Create a show before requesting a finale.",
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
+            None,
             render_backend_settings(None, backend_name, director_mode, max_new_tokens, temperature),
         )
 
@@ -1931,15 +1945,33 @@ def warm_up_backend(
         session.backend_temperature = selected_temperature
         if status.load_status == "loaded":
             session.director_log.append(f"OpenBMB warm-up loaded {status.model_id}.")
-            session.trace_events.append(f"openbmb_warmup_loaded:{status.model_id}:latency_ms={status.latest_latency_ms}")
+            add_trace_event(
+                session,
+                "backend_warmup",
+                backend_name="openbmb",
+                model_id=status.model_id,
+                latency_ms=status.latest_latency_ms,
+                validation_status="loaded",
+                fallback_used=False,
+            )
         else:
             reason = status.latest_fallback_reason or "unknown error"
             session.director_log.append(f"OpenBMB warm-up failed: {reason}.")
-            session.trace_events.append(f"openbmb_warmup_failed:{status.model_id}:{reason}")
+            add_trace_event(
+                session,
+                "backend_warmup",
+                backend_name="openbmb",
+                model_id=status.model_id,
+                latency_ms=status.latest_latency_ms,
+                validation_status=status.load_status,
+                fallback_used=True,
+                fallback_reason=reason,
+            )
     return (
         session,
         render_director_log(session),
         render_trace(session),
+        write_trace_json_file(session),
         render_backend_settings(
             session,
             "openbmb",
@@ -2030,11 +2062,16 @@ with gr.Blocks(title="AI Puppet Theater") as app:
     with gr.Accordion("Trace / Debug", open=False):
         trace_output = gr.Textbox(
             value=EMPTY_TRACE,
-            label="Trace Events",
-            lines=6,
+            label="Trace JSON Preview",
+            lines=10,
             interactive=False,
             elem_classes=["no-field-label"],
         )
+        trace_download = gr.DownloadButton(
+            "Download Trace JSON",
+            value=None,
+            elem_classes=["cue-action"],
+        )
     with gr.Accordion("Backend", open=False):
         backend_select = gr.Dropdown(
             choices=BACKEND_CHOICES,
@@ -2089,7 +2126,15 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     run_one_button.click(
         advance_one_beat,
@@ -2100,7 +2145,15 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     run_full_button.click(
         advance_full_act,
@@ -2112,7 +2165,15 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             temperature_input,
             deterministic_full_act_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     throw_prop_button.click(
         throw_audience_prop,
@@ -2124,7 +2185,15 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     summon_actor_button.click(
         summon_audience_actor,
@@ -2136,7 +2205,15 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     request_finale_button.click(
         request_audience_finale,
@@ -2147,12 +2224,20 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
         ],
-        outputs=[session_state, stage_output, transcript_output, director_output, trace_output, backend_output],
+        outputs=[
+            session_state,
+            stage_output,
+            transcript_output,
+            director_output,
+            trace_output,
+            trace_download,
+            backend_output,
+        ],
     )
     warm_up_button.click(
         warm_up_backend,
         inputs=[session_state, max_new_tokens_input, temperature_input],
-        outputs=[session_state, director_output, trace_output, backend_output],
+        outputs=[session_state, director_output, trace_output, trace_download, backend_output],
     )
     reset_button.click(
         reset_show,
@@ -2165,6 +2250,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             transcript_output,
             director_output,
             trace_output,
+            trace_download,
             backend_select,
             director_mode_select,
             max_new_tokens_input,

puppet_theater/actions.py

@@ -1,4 +1,5 @@
 from puppet_theater.models import Actor, TheaterSession
+from puppet_theater.trace import add_trace_event
 
 
 MAX_ACTORS = 4
@@ -13,7 +14,13 @@ def throw_prop(session: TheaterSession | None, prop_name: str) -> TheaterSession
     session.latest_prop = prop
     session.latest_audience_action = f"Audience threw {prop} onto the stage."
     session.director_log.append(session.latest_audience_action)
-    session.trace_events.append(f"prop_thrown:{prop}")
+    add_trace_event(
+        session,
+        "audience_action",
+        audience_action="throw_prop",
+        prop=prop,
+        action_summary=session.latest_audience_action,
+    )
     return session
 
 
@@ -25,7 +32,14 @@ def summon_actor(session: TheaterSession | None, actor_name: str) -> TheaterSess
     if len(session.actors) >= MAX_ACTORS:
         session.latest_audience_action = "Audience tried to summon an actor, but the stage is full."
         session.director_log.append(session.latest_audience_action)
-        session.trace_events.append("actor_summon_skipped:stage_full")
+        add_trace_event(
+            session,
+            "audience_action",
+            audience_action="summon_actor",
+            validation_status="skipped_stage_full",
+            fallback_used=False,
+            action_summary=session.latest_audience_action,
+        )
         return session
 
     actor = Actor(
@@ -39,7 +53,13 @@ def summon_actor(session: TheaterSession | None, actor_name: str) -> TheaterSess
     session.actors.append(actor)
     session.latest_audience_action = f"Audience summoned {name}."
     session.director_log.append(session.latest_audience_action)
-    session.trace_events.append(f"actor_summoned:{name}")
+    add_trace_event(
+        session,
+        "audience_action",
+        audience_action="summon_actor",
+        summoned_actor=name,
+        action_summary=session.latest_audience_action,
+    )
     return session
 
 
@@ -50,5 +70,10 @@ def request_finale(session: TheaterSession | None) -> TheaterSession | None:
     session.finale_requested = True
     session.latest_audience_action = "Audience requested the finale."
     session.director_log.append(session.latest_audience_action)
-    session.trace_events.append("finale_requested")
+    add_trace_event(
+        session,
+        "audience_action",
+        audience_action="request_finale",
+        action_summary=session.latest_audience_action,
+    )
     return session

puppet_theater/director.py

@@ -17,6 +17,7 @@ from puppet_theater.backends import (
 )
 from puppet_theater.models import Actor, Beat, DirectorDecision, TheaterSession
 from puppet_theater.prompts import DIRECTOR_DECISION_PROMPT
+from puppet_theater.trace import add_trace_event
 
 
 BEAT_ARC = [
@@ -344,7 +345,12 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
 
     if session.beat_index >= session.max_beats:
         session.director_log.append("Curtain already fallen; no new beat added.")
-        session.trace_events.append("beat_skipped:curtain_already_fallen")
+        add_trace_event(
+            session,
+            "beat_skipped",
+            validation_status="curtain_already_fallen",
+            fallback_used=False,
+        )
         return session
 
     director_generation = choose_director_decision(session)
@@ -368,29 +374,31 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
         session.director_log.append(f"Director model id: {director_generation.model_id}.")
     if director_generation.error:
         session.director_log.append(f"Director fallback reason: {director_generation.error}.")
-    session.trace_events.append(
-        "director_decision:"
-        f"mode={director_generation.director_mode}:"
-        f"speaker={speaker.name}:"
-        f"beat={decision.beat_type}:"
-        f"uses_prop={decision.uses_prop}:"
-        f"reveal_secret={decision.reveal_secret}:"
-        f"should_end={decision.should_end_scene}:"
-        f"validation={director_generation.validation_status}:"
-        f"fallback={director_generation.fallback_used}:"
-        f"model={director_generation.model_id or 'none'}:"
-        f"latency_ms={director_generation.latency_ms}:"
-        f"reason={_trace_text(director_generation.reason_summary)}"
+    add_trace_event(
+        session,
+        "director_decision",
+        speaker=speaker.name,
+        beat_type=decision.beat_type,
+        backend_name=director_generation.director_mode,
+        model_id=director_generation.model_id,
+        latency_ms=director_generation.latency_ms,
+        validation_status=director_generation.validation_status,
+        fallback_used=director_generation.fallback_used,
+        fallback_reason=director_generation.error,
+        reason_summary=director_generation.reason_summary,
+        uses_prop=decision.uses_prop,
+        reveal_secret=decision.reveal_secret,
+        should_end_scene=decision.should_end_scene,
     )
-    if director_generation.fallback_used:
-        session.trace_events.append(f"director_fallback_used:{director_generation.validation_status}")
     if director_generation.error:
-        session.trace_events.append(
-            "director_error:"
-            f"mode={director_generation.director_mode}:"
-            f"model={director_generation.model_id or 'none'}:"
-            f"type={director_generation.validation_status}:"
-            f"message={_trace_text(director_generation.error)}"
+        add_trace_event(
+            session,
+            "director_error",
+            backend_name=director_generation.director_mode,
+            model_id=director_generation.model_id,
+            validation_status=director_generation.validation_status,
+            fallback_used=director_generation.fallback_used,
+            fallback_reason=director_generation.error,
         )
 
     backend_generation = generate_actor_response(session, decision, speaker, prop)
@@ -410,7 +418,7 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     if prop is not None:
         session.latest_prop = None
         session.director_log.append(f"{speaker.name} picked up {prop} and used it in the scene.")
-        session.trace_events.append(f"prop_used:{prop}:{speaker.name}")
+        add_trace_event(session, "prop_used", speaker=speaker.name, prop=prop)
 
     session.director_log.append(
         f"Beat {session.beat_index}/{session.max_beats}: {decision.beat_type} assigned to {speaker.name}."
@@ -426,39 +434,50 @@ def run_one_beat(session: TheaterSession | None) -> TheaterSession | None:
     if backend_generation.error:
         session.director_log.append(f"Backend fallback reason: {backend_generation.error}.")
 
-    session.trace_events.append(f"beat_added:{session.beat_index}:{decision.beat_type}")
-    session.trace_events.append(
-        "actor_response:"
-        f"speaker={speaker.name}:"
-        f"backend={backend_generation.backend_name}:"
-        f"validation={backend_generation.validation_status}"
+    add_trace_event(
+        session,
+        "beat_added",
+        beat_index=session.beat_index,
+        beat_type=decision.beat_type,
+        speaker=speaker.name,
+        stage_effect=beat.stage_effect,
+    )
+    add_trace_event(
+        session,
+        "actor_response",
+        beat_index=session.beat_index,
+        speaker=speaker.name,
+        backend_name=backend_generation.backend_name,
+        model_id=backend_generation.model_id,
+        latency_ms=backend_generation.latency_ms,
+        validation_status=backend_generation.validation_status,
+        fallback_used=backend_generation.fallback_used,
+        fallback_reason=backend_generation.error,
+        load_status=backend_generation.load_status,
     )
-    if backend_generation.fallback_used:
-        session.trace_events.append(f"fallback_used:{backend_generation.backend_name}:{backend_generation.validation_status}")
     if backend_generation.error:
-        session.trace_events.append(
-            "backend_error:"
-            f"backend={backend_generation.backend_name}:"
-            f"model={backend_generation.model_id or 'none'}:"
-            f"type={backend_generation.validation_status}:"
-            f"message={_trace_text(backend_generation.error)}"
+        add_trace_event(
+            session,
+            "backend_error",
+            beat_index=session.beat_index,
+            speaker=speaker.name,
+            backend_name=backend_generation.backend_name,
+            model_id=backend_generation.model_id,
+            validation_status=backend_generation.validation_status,
+            fallback_used=backend_generation.fallback_used,
+            fallback_reason=backend_generation.error,
         )
-    session.trace_events.append(
-        "backend_result:"
-        f"{backend_generation.backend_name}:"
-        f"model={backend_generation.model_id or 'none'}:"
-        f"load_status={backend_generation.load_status}:"
-        f"fallback={backend_generation.fallback_used}:"
-        f"validation={backend_generation.validation_status}:"
-        f"latency_ms={backend_generation.latency_ms}"
-    )
 
     if decision.should_end_scene or decision.beat_type == "finale":
         session.beat_index = session.max_beats
         session.finale_requested = True
         session.director_log.append("Finale reached; curtain falls cleanly.")
-        session.trace_events.append("finale_triggered")
-        session.trace_events.append("scene_completed")
+        add_trace_event(
+            session,
+            "scene_completed",
+            beat_index=session.beat_index,
+            reason_summary="Finale reached; curtain falls cleanly.",
+        )
 
     return session
 

puppet_theater/models.py

@@ -1,6 +1,8 @@
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from uuid import uuid4
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field, field_validator
 
@@ -90,6 +92,8 @@ class TheaterSession:
     premise: str
     setting: str
     actors: list[Actor]
+    session_id: str = field(default_factory=lambda: uuid4().hex[:12])
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
     beat_index: int = 0
     max_beats: int = 6
     transcript: list[Beat] = field(default_factory=list)
@@ -97,7 +101,7 @@ class TheaterSession:
     latest_prop: str | None = None
     latest_audience_action: str | None = None
     director_log: list[str] = field(default_factory=list)
-    trace_events: list[str] = field(default_factory=list)
+    trace_events: list[dict[str, Any] | str] = field(default_factory=list)
     finale_requested: bool = False
     backend_name: str = "deterministic"
     backend_model_id: str | None = None

puppet_theater/session.py

@@ -1,4 +1,5 @@
 from puppet_theater.models import Actor, TheaterSession
+from puppet_theater.trace import add_trace_event
 
 
 def _clean_premise(premise: str) -> str:
@@ -77,15 +78,7 @@ def create_show_from_premise(
         f"Setting selected: {setting}.",
         "Three puppet actors are waiting for the first beat.",
     ]
-    trace_events = [
-        "show_created",
-        "actors_created:3",
-        "director_plan_created",
-        f"backend_active:{active_backend}",
-        f"director_mode_active:{active_director_mode}",
-    ]
-
-    return TheaterSession(
+    session = TheaterSession(
         show_title=show_title,
         premise=cleaned_premise,
         setting=setting,
@@ -97,7 +90,7 @@ def create_show_from_premise(
         latest_prop=None,
         latest_audience_action=None,
         director_log=director_log,
-        trace_events=trace_events,
+        trace_events=[],
         finale_requested=False,
         backend_name=active_backend,
         backend_model_id=backend_model_id,
@@ -106,3 +99,21 @@ def create_show_from_premise(
         director_mode=active_director_mode,
         play_opening_curtain=True,
     )
+    add_trace_event(
+        session,
+        "show_created",
+        backend_name=active_backend,
+        model_id=backend_model_id,
+        director_mode=active_director_mode,
+        actor_count=len(actors),
+        validation_status="valid",
+        fallback_used=False,
+    )
+    add_trace_event(session, "actors_created", actor_count=len(actors))
+    add_trace_event(
+        session,
+        "director_plan_created",
+        director_mode=active_director_mode,
+        reason_summary="Deterministic six-beat show plan created.",
+    )
+    return session

puppet_theater/trace.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+import os
+import re
+import tempfile
+from typing import Any
+
+from puppet_theater.models import TheaterSession
+
+
+APP_NAME = "AI Puppet Theater"
+TRACE_VERSION = "1.0"
+_MAX_TEXT_CHARS = 500
+_PRIVATE_PATH_PATTERNS = [
+    re.compile(r"/Users/[^\s\"'<>:]+(?:/[^\s\"'<>:]+)*"),
+    re.compile(r"/private/(?:tmp|var)/[^\s\"'<>:]+(?:/[^\s\"'<>:]+)*"),
+    re.compile(r"/tmp/[^\s\"'<>:]+(?:/[^\s\"'<>:]+)*"),
+]
+
+
+def add_trace_event(session: TheaterSession, event_type: str, **fields: Any) -> None:
+    event: dict[str, Any] = {
+        "type": sanitize_value(event_type),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "step": len(session.trace_events) + 1,
+    }
+    if session.beat_index is not None:
+        event["beat_index"] = session.beat_index
+    for key, value in fields.items():
+        if value is not None:
+            event[key] = sanitize_value(value)
+    session.trace_events.append(event)
+
+
+def export_trace(session: TheaterSession | None) -> dict[str, Any] | None:
+    if session is None:
+        return None
+
+    actor_model_id = session.backend_model_id
+    director_model_id = _model_id_for_mode(session.director_mode)
+    active_model_id = actor_model_id or director_model_id
+    return {
+        "app_name": APP_NAME,
+        "trace_version": TRACE_VERSION,
+        "session_id": sanitize_value(session.session_id),
+        "created_at": sanitize_value(session.created_at),
+        "premise": sanitize_value(session.premise),
+        "title": sanitize_value(session.show_title),
+        "setting": sanitize_value(session.setting),
+        "active_backend": sanitize_value(session.backend_name),
+        "actor_backend": sanitize_value(session.backend_name),
+        "director_mode": sanitize_value(session.director_mode),
+        "director_backend": sanitize_value(session.director_mode),
+        "model_id": sanitize_value(active_model_id),
+        "actor_model_id": sanitize_value(actor_model_id),
+        "director_model_id": sanitize_value(director_model_id),
+        "events": normalize_trace_events(session),
+    }
+
+
+def render_trace_json(session: TheaterSession | None) -> str:
+    payload = export_trace(session)
+    if payload is None:
+        return "No trace events yet."
+    return json.dumps(payload, indent=2, sort_keys=False)
+
+
+def write_trace_json_file(session: TheaterSession | None) -> str | None:
+    payload = export_trace(session)
+    if payload is None:
+        return None
+
+    safe_session_id = re.sub(r"[^a-zA-Z0-9_-]+", "-", str(payload["session_id"]))[:48] or "session"
+    filename = f"ai-puppet-theater-trace-{safe_session_id}.json"
+    path = os.path.join(tempfile.gettempdir(), filename)
+    with open(path, "w", encoding="utf-8") as trace_file:
+        json.dump(payload, trace_file, indent=2, ensure_ascii=False)
+        trace_file.write("\n")
+    return path
+
+
+def normalize_trace_events(session: TheaterSession) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for index, raw_event in enumerate(session.trace_events, start=1):
+        if isinstance(raw_event, dict):
+            event = {str(key): sanitize_value(value) for key, value in raw_event.items() if value is not None}
+            event.setdefault("type", "event")
+            event.setdefault("step", index)
+            normalized.append(event)
+            continue
+
+        normalized.append(
+            {
+                "type": "legacy_event",
+                "step": index,
+                "message": sanitize_value(raw_event),
+            }
+        )
+    return normalized
+
+
+def sanitize_value(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            str(key): sanitize_value(item)
+            for key, item in value.items()
+            if item is not None and not _is_sensitive_key(str(key))
+        }
+    if isinstance(value, list):
+        return [sanitize_value(item) for item in value]
+    if isinstance(value, tuple):
+        return [sanitize_value(item) for item in value]
+    if isinstance(value, str):
+        return _sanitize_text(value)
+    return value
+
+
+def _sanitize_text(value: str) -> str:
+    text = " ".join(value.split())
+    if "Traceback (most recent call last)" in text:
+        text = "Traceback redacted"
+    for secret_name in ("HF_TOKEN", "HUGGINGFACEHUB_API_TOKEN"):
+        secret = os.getenv(secret_name)
+        if secret:
+            text = text.replace(secret, "[redacted]")
+    text = re.sub(r"\b(HF_TOKEN|HUGGINGFACEHUB_API_TOKEN)\s*=\s*\S+", r"\1=[redacted]", text)
+    for pattern in _PRIVATE_PATH_PATTERNS:
+        text = pattern.sub("[redacted-path]", text)
+    return text[:_MAX_TEXT_CHARS].rstrip()
+
+
+def _is_sensitive_key(key: str) -> bool:
+    lowered = key.lower()
+    return "token" in lowered or "secret" in lowered or "password" in lowered
+
+
+def _model_id_for_mode(mode: str | None) -> str | None:
+    if mode == "openbmb":
+        return os.getenv("OPENBMB_MODEL_ID", "openbmb/MiniCPM5-1B")
+    if mode == "hf_api":
+        return os.getenv("HF_API_MODEL_ID", "Qwen/Qwen3-4B-Instruct-2507:nscale")
+    return None