@meridiona/meridian-darwin-arm64 1.67.0 → 1.69.0

package/.env.example

@@ -45,9 +45,14 @@
 # If both are present, OAuth wins. JIRA_PROJECT_KEYS applies to either.
 # ---------------------------------------------------------------------------
 
-# (A) OAuth needs NO config — Meridian ships a public client id. The vars below are
-#     optional overrides (e.g. a self-hosted app or a non-default redirect port).
+# (A) OAuth in a RELEASE build needs NO config — Meridian ships a public client id
+#     and bakes the matching client secret in at build time (CI-only; never
+#     committed). A LOCAL SOURCE BUILD (cargo run / npm run tauri dev) has no
+#     baked-in secret, so browser OAuth login always fails there with "Jira
+#     OAuth requires a client secret..." until you set JIRA_OAUTH_CLIENT_SECRET
+#     below (ask a Meridiona team member for it) — or just use (B) instead.
 # JIRA_OAUTH_CLIENT_ID=your-atlassian-app-client-id   # override the baked-in client id
+# JIRA_OAUTH_CLIENT_SECRET=your-atlassian-app-client-secret  # REQUIRED for OAuth on a source build
 # JIRA_OAUTH_REDIRECT_PORT=9123      # must match the app's registered redirect
                                      # http://127.0.0.1:<port>/callback
 

package/VERSION

@@ -1 +1 @@
-1.67.0
+1.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridiona/meridian-darwin-arm64",
-  "version": "1.67.0",
+  "version": "1.69.0",
   "description": "Prebuilt Meridian app for macOS arm64 (daemon binary + dashboard + Python services). Installed via @meridiona/meridian.",
   "homepage": "https://github.com/Meridiona/meridian",
   "repository": {

package/scripts/install-openobserve-daemon.sh

@@ -267,13 +267,15 @@ st, body = call("GET", f"/api/{org}/dashboards")
 if st != 200:
     print(f"  ⚠ could not list dashboards ({st}) — skipping dashboard import")
     sys.exit(0)
-existing = set()
+id_map = {}  # title -> dashboard_id
 for d in json.loads(body).get("dashboards", []):
-    for v in ("v1", "v2", "v3", "v4", "v5", "v6"):
+    did = d.get("dashboard_id", "")
+    for v in ("v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8"):
         if d.get(v) and d[v].get("title"):
-            existing.add(d[v]["title"])
+            id_map[d[v]["title"]] = did
+            break
 
-created = skipped = failed = 0
+created = updated = failed = 0
 for path in sorted(glob.glob(os.path.join(dash_dir, "*.json"))):
     try:
         dash = json.load(open(path))
@@ -282,18 +284,32 @@ for path in sorted(glob.glob(os.path.join(dash_dir, "*.json"))):
         failed += 1
         continue
     title = dash.get("title", "")
-    if title in existing:
-        skipped += 1
-        continue
-    st, resp = call("POST", f"/api/{org}/dashboards?folder=default", dash)
-    if st in (200, 201):
-        created += 1
-        print(f"  ✓ imported dashboard: {title}")
+    if title in id_map:
+        # OO PUT requires an internal hash that can't be round-tripped reliably.
+        # Delete + re-create is the safe upsert path.
+        did = id_map[title]
+        st_d, _ = call("DELETE", f"/api/{org}/dashboards/{did}")
+        if st_d not in (200, 204):
+            failed += 1
+            print(f"  ⚠ delete failed {title} ({st_d}) — skipping")
+            continue
+        st, resp = call("POST", f"/api/{org}/dashboards?folder=default", dash)
+        if st in (200, 201):
+            updated += 1
+            print(f"  ✓ updated dashboard: {title}")
+        else:
+            failed += 1
+            print(f"  ⚠ failed to re-create {os.path.basename(path)} ({st}): {resp[:200].decode(errors='replace')}")
     else:
-        failed += 1
-        print(f"  ⚠ failed to import {os.path.basename(path)} ({st}): {resp[:200].decode(errors='replace')}")
+        st, resp = call("POST", f"/api/{org}/dashboards?folder=default", dash)
+        if st in (200, 201):
+            created += 1
+            print(f"  ✓ imported dashboard: {title}")
+        else:
+            failed += 1
+            print(f"  ⚠ failed to import {os.path.basename(path)} ({st}): {resp[:200].decode(errors='replace')}")
 
-print(f"→ dashboards: {created} imported, {skipped} already present, {failed} failed")
+print(f"→ dashboards: {created} imported, {updated} updated, {failed} failed")
 PYEOF
     return 0
 }

package/services/agents/mlx_classifier.py

@@ -18,7 +18,7 @@ from typing import Any, Iterator
 from agents import model_registry, observability
 
 log = logging.getLogger("agents.mlx_classifier")
-tracer = observability.setup("meridian-mlx-classifier")
+tracer = observability.setup("meridian-mlx-server")
 
 # Generative/classifier checkpoint — resolved from the model registry (the single
 # source of truth for all three pipeline models), env-overridable via MERIDIAN_LLM_ID.
@@ -45,6 +45,31 @@ _in_flight = 0
 _last_used = time.monotonic()
 
 
+def _invalidate_dependent_caches() -> None:
+    """Drop caches in other modules keyed off the (about-to-be-freed) model object.
+
+    ``agents.structured`` caches an outlines MLXLM wrapper + compiled FSM
+    Generator(s) per ``id(bundle.model)`` — without this call those caches
+    only get cleared lazily, the next time a structured-generation call
+    happens to see a new model id. That left the "evicted" model (and its
+    outlines_core Index/Guide/Vocabulary, which carry Python-side reference
+    cycles) fully resident for the whole gap: it both defeated this module's
+    single-slot residency guarantee (two generative models briefly alive at
+    once) and, since eviction fires here often — every reranker↔classifier
+    swap — let that stale generation pile up across many reload cycles
+    before Python's own GC schedule swept it, producing multi-GB/hour
+    malloc-zone growth invisible to ``mx.get_active_memory()`` (that call
+    only accounts Metal/unified GPU memory, not this CPU-side object graph).
+    Lazy import: ``agents.structured`` is not a dependency this module needs
+    at import time, only at eviction time.
+    """
+    try:
+        from agents import structured
+        structured.invalidate()
+    except Exception:  # noqa: BLE001 — cache invalidation is best-effort
+        pass
+
+
 def _get_model() -> _ModelBundle:
     """Return the loaded model bundle, loading from disk on the first call.
 
@@ -132,6 +157,7 @@ def maybe_evict_idle(idle_s: float | None = None) -> float | None:
             mx, before = None, 0
         _model_cache.clear()
         _tokenizer_cache.clear()
+        _invalidate_dependent_caches()
         gc.collect()
         freed = 0.0
         if mx is not None:
@@ -167,6 +193,7 @@ def evict_resident_model() -> float | None:
             mx, before = None, 0
         _model_cache.clear()
         _tokenizer_cache.clear()
+        _invalidate_dependent_caches()
         gc.collect()
         freed = 0.0
         if mx is not None:

package/services/agents/observability.py

@@ -3,39 +3,54 @@
 A single `setup(agent_name)` call wires up:
 
   * an OTel `TracerProvider` with `service.name=agent_name`
-  * a `BatchSpanProcessor` writing OTLP/HTTP-protobuf spans to the durable
-    telemetry spool (the Rust daemon's shipper drains it to OpenObserve)
-  * a `LoggerProvider` + spool log handler so every `logging.LogRecord` is also
-    spooled (correlated to the active span), mirroring the Rust daemon's
-    `OpenTelemetryTracingBridge`
+  * export ALWAYS goes through the durable disk spool
+    (`~/.meridian/telemetry/pending/`), never a live HTTP call from this
+    process — see "Spool-only export" below
+  * a `LoggerProvider` + matching log handler so every `logging.LogRecord`
+    is correlated to the active span via trace_id/span_id
   * W3C `TraceContextTextMapPropagator` as the global propagator so each
     agent can pick up the Rust daemon's `traceparent` and continue the trace
   * `LoggingInstrumentor` so every `logging.LogRecord` carries
     `otelTraceID` / `otelSpanID` attributes for OpenObserve correlation
   * a JSON formatter (`python-json-logger`) writing daily-rotated JSONL files
-    under `~/.meridian/logs/{agent_name}.jsonl` plus stderr — both ingestable
-    by OpenObserve's log pipeline without further parsing.
-
-Export is gated by the SAME `~/.meridian/settings.json` the Rust daemon reads —
-the `otlp_enabled` toggle — so the dashboard Settings page is the single source
-of truth for both processes. Delivery (endpoint + Basic-auth credentials) is
-owned entirely by the Rust shipper; Python only ever writes to the spool. The
-legacy `MERIDIAN_OO_AUTH` env credential is deprecated and ignored.
+    under `~/.meridian/logs/{agent_name}.jsonl` plus stderr
+
+Export gate: `~/.meridian/settings.json` `otlp_enabled` toggle. When on, every
+span/log batch is written to the spool (`_write_spool`, an atomic
+tmp-then-rename into `~/.meridian/telemetry/pending/`) — the exact same
+`<signal>-<unix_micros>-<seq>.otlp` layout `src/telemetry_spool/writer.rs`
+produces. Generation (this process) and delivery are fully decoupled:
+
+  * The Rust daemon's `telemetry_spool::shipper` background task drains
+    `pending/` into OpenObserve whenever it's reachable, independent of
+    whether this process is even still running — `ship_one` in
+    `telemetry_spool/mod.rs` classifies failures as Terminal (payload is bad,
+    quarantined) or Retryable (network/5xx/429, retried next tick), so a
+    down or flaky OpenObserve never loses or corrupts anything, it just
+    backs up on disk until OO comes back.
+  * `meridian telemetry export`/`import` (`telemetry_spool/cli.rs`) lets a
+    user hand someone else the pending spool directly (or import one) —
+    the "give a customer's log bundle to support, load it into our own
+    OpenObserve" path this architecture exists for.
+
+This process NEVER opens a live connection to OpenObserve itself. Earlier
+revisions shipped directly via `OTLPSpanExporter`/`OTLPLogExporter` when OO
+credentials were configured in settings.json (skipping the Rust daemon) —
+that meant a long-running process (the MLX server) held live HTTP
+export/retry state against OpenObserve, and when OO went down for hours,
+continuous failed-export retries correlated with the process's memory
+growing from ~100MB to 20+GB. Spool-only export removes that whole failure
+class: writing to disk can't hang, retry-loop, or accumulate connection
+state, and the already-hardened Rust shipper (atomic writes, terminal/
+retryable classification, quarantine) is the only thing that ever talks to
+OpenObserve.
 
 `extract_parent_context(traceparent)` is the helper agents use to continue
 a span emitted by another process — typically the Rust ETL or another
 agent stage.
 
 Idempotent: calling `setup` twice is a no-op for the second call (returns
-the existing tracer). This matters because both the daemon and the
-single-shot CLI paths funnel through the same module.
-
-Spool durability: when `otlp_enabled` is true (regardless of whether
-credentials are present), spans and logs are written atomically to
-`~/.meridian/telemetry/pending/<signal>-<unix_micros>-<seq>.otlp` via
-`SpoolSpanExporter` and `SpoolLogExporter`.  The Rust daemon's shipper
-task drains that shared directory to OpenObserve — Python does NOT need
-its own shipper, and credential resolution lives there, not here.
+the existing tracer).
 """
 from __future__ import annotations
 
@@ -55,10 +70,10 @@ from opentelemetry.context import Context
 from opentelemetry.instrumentation.logging import LoggingInstrumentor
 from opentelemetry.propagate import set_global_textmap
 from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
-from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, LogExportResult
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, SimpleLogRecordProcessor, LogExportResult
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExportResult
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor, SpanExportResult
 from opentelemetry.trace.propagation.tracecontext import (
     TraceContextTextMapPropagator,
 )
@@ -200,11 +215,9 @@ class SpoolLogExporter:
 
 # ──────────────────────── Config ───────────────────────────────────────────────
 DEFAULT_LOG_DIR = Path.home() / ".meridian" / "logs"
-# Single source of truth for the export TOGGLE — the SAME file the Rust daemon
-# reads (see `src/observability.rs::resolve_otlp_target`). Delivery credentials
-# live there too: the dashboard Settings page writes here and the Rust shipper
-# picks them up. This process only reads `otlp_enabled` to decide whether to
-# spool — it never delivers, so it needs no endpoint/credentials of its own.
+# Same settings.json the Rust daemon reads — only the otlp_enabled toggle
+# matters here now; oo_email/oo_password are read by the Rust shipper, not
+# this process (see the module docstring's "Spool-only export" section).
 _SETTINGS_PATH = Path(
     os.environ.get("MERIDIAN_SETTINGS_PATH")
     or (Path.home() / ".meridian" / "settings.json")
@@ -230,13 +243,7 @@ def _load_settings() -> dict[str, object]:
 
 
 def _is_otlp_enabled() -> bool:
-    """Return True when the otlp_enabled toggle is on and tracing is not disabled.
-
-    Deliberately does NOT check credentials — used to gate the spool exporters
-    so telemetry is captured even when OO credentials are absent (the Rust
-    shipper delivers when they are provided later, and warns once if a user
-    leaves the toggle on with no credentials).
-    """
+    """Return True when the otlp_enabled toggle is on and tracing is not disabled."""
     if os.environ.get("MERIDIAN_TRACING_DISABLED", "").lower() in ("1", "true", "yes"):
         return False
     return bool(_load_settings().get("otlp_enabled"))
@@ -280,22 +287,16 @@ def setup(agent_name: str) -> trace.Tracer:
 
 
 def shutdown() -> None:
-    """Flush and shut down the global TracerProvider.
+    """Shut down the global TracerProvider and log provider.
 
-    Must be called before a short-lived process exits — BatchSpanProcessor
-    queues spans asynchronously and drops them on interpreter shutdown unless
-    explicitly flushed.
+    BatchSpanProcessor/BatchLogRecordProcessor queue spans asynchronously;
+    calling shutdown() flushes the queue before releasing resources.
     """
     provider = trace.get_tracer_provider()
-    if hasattr(provider, "force_flush"):
-        provider.force_flush(timeout_millis=5_000)
     if hasattr(provider, "shutdown"):
         provider.shutdown()
 
-    # Flush queued log records too — BatchLogRecordProcessor drops them on
-    # interpreter exit otherwise, the same hazard as spans.
     if _LOGGER_PROVIDER is not None:
-        _LOGGER_PROVIDER.force_flush(timeout_millis=5_000)
         _LOGGER_PROVIDER.shutdown()
 
 
@@ -312,32 +313,36 @@ def extract_parent_context(traceparent: Optional[str]) -> Optional[Context]:
 
 
 # ──────────────────────── Tracing setup ────────────────────────────────────────
+# Spool-only by design — see the module docstring's "Spool-only export"
+# section for why this process never opens a live connection to OpenObserve.
+# `src/telemetry_spool/shipper.rs` (Rust daemon, runs independently) is the
+# only thing that ever ships these bytes to OO; `meridian telemetry export/
+# import` is the manual escape hatch when the daemon isn't running at all.
+
+
 def _configure_tracing(agent_name: str) -> None:
-    resource = Resource.create({"service.name": agent_name})
-    provider = TracerProvider(resource=resource)
+    # The W3C propagator is always installed so traceparent round-trips work.
+    set_global_textmap(TraceContextTextMapPropagator())
 
-    # Wire the spool exporter when otlp_enabled is true (even without creds).
-    # The Rust shipper drains the shared spool dir when a target is available.
-    if _is_otlp_enabled():
-        provider.add_span_processor(BatchSpanProcessor(SpoolSpanExporter()))
+    if not _is_otlp_enabled():
+        return
 
-    # Set as the global provider. OTel's `set_tracer_provider` warns if
-    # someone already configured a provider in-process; we accept that and
-    # overwrite — the agent process is the authority on its own telemetry.
+    resource = Resource.create({"service.name": agent_name})
+    provider = TracerProvider(resource=resource)
+    # BatchSpanProcessor avoids blocking inference threads on each span end;
+    # SpoolSpanExporter itself is a synchronous local file write, so this can
+    # never hang, retry-loop, or accumulate connection state regardless of
+    # whether OpenObserve is reachable.
+    provider.add_span_processor(BatchSpanProcessor(SpoolSpanExporter()))
     trace.set_tracer_provider(provider)
-    set_global_textmap(TraceContextTextMapPropagator())
 
 
 def _configure_log_export(agent_name: str) -> Optional[logging.Handler]:
-    """Build a spool-logs handler so every `log.*` record reaches OpenObserve,
-    correlated to the active span by trace_id/span_id — the Python counterpart
-    of the Rust daemon's `OpenTelemetryTracingBridge`.
-
-    Returns the handler (caller attaches it to root) or `None` when export is
-    disabled, in which case logs still go to the JSONL file + stdout/stderr.
+    """Build an OTel log handler so every ``log.*`` record reaches OpenObserve,
+    correlated to the active span by trace_id/span_id.
 
-    When `otlp_enabled` is true the spool log exporter is always wired (even
-    without credentials) — the Rust shipper handles delivery.
+    Returns the handler (caller attaches it to root) or ``None`` when export is
+    disabled — logs still go to the JSONL file + stdout/stderr regardless.
     """
     global _LOGGER_PROVIDER
 
@@ -346,6 +351,8 @@ def _configure_log_export(agent_name: str) -> Optional[logging.Handler]:
 
     resource = Resource.create({"service.name": agent_name})
     provider = LoggerProvider(resource=resource)
+    # BatchLogRecordProcessor so log export never blocks callers — see
+    # _configure_tracing above for why SpoolLogExporter is always used.
     provider.add_log_record_processor(BatchLogRecordProcessor(SpoolLogExporter()))
     set_logger_provider(provider)
     _LOGGER_PROVIDER = provider
@@ -456,19 +463,106 @@ def current_traceparent() -> Optional[str]:
     return carrier.get("traceparent")
 
 
-def instrument_agno() -> None:
-    """Instrument the agno framework for OpenTelemetry tracing.
+# Process-level handle so the agno TracerProvider isn't garbage-collected.
+_AGNO_TRACER_PROVIDER = None
 
-    No-op when openinference-instrumentation-agno is not installed; the package
-    is optional and the server must start cleanly without it.
+
+def _build_agno_db_exporter(db, workflow_id: str, agent_id: str):
+    """agno ``DatabaseSpanExporter`` subclass that stamps the pipeline identity
+    onto each trace's ROOT span.
+
+    AgentOS hides any trace whose ``workflow_id`` AND ``agent_id`` are both
+    null. With OpenObserve off, the meridian wrapper span (``worklog.hour``) is
+    non-recording, so agno's worklog Workflow runs as its OWN root trace; its
+    root ``*.run`` span is parentless here and gets the ids, surfacing the trace
+    in the dashboard. Child spans are written unchanged.
+    """
+    from collections import defaultdict
+
+    from agno.tracing.exporter import DatabaseSpanExporter
+    from agno.tracing.schemas import Span
+    from opentelemetry.sdk.trace.export import SpanExportResult
+
+    class _AgnoDbExporter(DatabaseSpanExporter):
+        def export(self, spans):  # type: ignore[override]
+            if self._shutdown:
+                return SpanExportResult.FAILURE
+            if not spans:
+                return SpanExportResult.SUCCESS
+            converted = []
+            for s in spans:
+                try:
+                    cs = Span.from_otel_span(s)
+                except Exception:  # noqa: BLE001 — skip a span we can't convert
+                    continue
+                if not cs.parent_span_id:
+                    attrs = dict(cs.attributes or {})
+                    attrs.setdefault("workflow_id", workflow_id)
+                    attrs.setdefault("agent_id", agent_id)
+                    # Group hour-runs into one AgentOS session. agno normally
+                    # stamps session_id when run(session_id=...) is passed; this
+                    # is a fallback that derives the day-level session from the
+                    # run_id ("wl-<day>T<hh>" → "wl-<day>") so the trace always
+                    # surfaces under a session in the dashboard.
+                    if not (attrs.get("session_id") or attrs.get("agno.session.id")):
+                        rid = attrs.get("run_id") or attrs.get("agno.run.id") or ""
+                        if isinstance(rid, str) and "T" in rid:
+                            attrs["session_id"] = rid.rsplit("T", 1)[0]
+                    cs.attributes = attrs
+                converted.append(cs)
+            if not converted:
+                return SpanExportResult.SUCCESS
+            by_trace: dict = defaultdict(list)
+            for cs in converted:
+                by_trace[cs.trace_id].append(cs)
+            try:
+                self._export_sync(by_trace)  # SqliteDb is synchronous
+            except Exception as e:  # noqa: BLE001
+                logging.getLogger(__name__).warning("agno trace export failed: %s", e)
+                return SpanExportResult.FAILURE
+            return SpanExportResult.SUCCESS
+
+    return _AgnoDbExporter(db=db)
+
+
+def setup_agno_tracing(
+    db_file: Optional[str] = None,
+    workflow_id: str = "worklog-hour",
+    agent_id: str = "meridian-worklog-pipeline",
+):
+    """Route agno's native (openinference) spans — and ONLY those — to a SqliteDb
+    the AgentOS viewer reads.
+
+    The TracerProvider here is EXPLICIT, not global: meridian's own manual spans
+    live on the no-op global provider and never reach this exporter, so the
+    dashboard shows agno's ``tracing=True`` output alone. Idempotent per process.
+    Returns the provider (or ``None`` if agno/openinference aren't installed).
     """
+    global _AGNO_TRACER_PROVIDER
+    if _AGNO_TRACER_PROVIDER is not None:
+        return _AGNO_TRACER_PROVIDER
     try:
-        from opentelemetry.instrumentation.agno import AgnoInstrumentor  # type: ignore[import]
-        AgnoInstrumentor().instrument()
-    except ImportError:
-        logging.getLogger(__name__).debug(
-            "opentelemetry-instrumentation-agno not installed; agno spans will not be exported"
+        from agno.db.sqlite import SqliteDb
+        from openinference.instrumentation.agno import AgnoInstrumentor
+        from opentelemetry.sdk.trace import TracerProvider as _TP
+        from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+    except ImportError as e:
+        logging.getLogger(__name__).warning(
+            "setup_agno_tracing: dependencies missing (%s); agno tracing disabled", e
         )
+        return None
+
+    path = db_file or os.environ.get("AGNO_TRACE_DB") or str(
+        Path("~/.meridian/agno_traces.db").expanduser()
+    )
+    path = str(Path(path).expanduser())
+    exporter = _build_agno_db_exporter(SqliteDb(db_file=path), workflow_id, agent_id)
+    provider = _TP()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    AgnoInstrumentor().instrument(tracer_provider=provider)
+    _AGNO_TRACER_PROVIDER = provider
+    logging.getLogger(__name__).info("setup_agno_tracing: agno spans -> %s", path)
+    return provider
 
 
 def preview(text: Optional[str], max_chars: int = 200) -> str:
@@ -478,4 +572,121 @@ def preview(text: Optional[str], max_chars: int = 200) -> str:
     return text[:max_chars] + ("…" if len(text) > max_chars else "")
 
 
-__all__ = ["setup", "extract_parent_context", "instrument_agno", "current_traceparent", "preview"]
+def record_gen_params(
+    span,
+    *,
+    temp: float,
+    max_tokens: int,
+    thinking_budget: int,
+    budget_forced: bool,
+    enable_thinking: bool = True,
+    model: str = "",
+) -> None:
+    """Stamp the generation parameters used for ONE LLM call onto its span.
+
+    Records the per-call sampling settings — the variable ``temp`` plus the
+    shared constants from :mod:`agents.thinking` (top_p / top_k / presence /
+    repetition penalty) — together with the thinking-budget config and whether
+    the hard cap actually fired (``budget_forced``). Call inside the call's main
+    span so every LLM span in the worklog trace shows exactly which parameters
+    produced its output. ``model`` is set only when non-empty (some callers set
+    it earlier on the span themselves).
+    """
+    from agents.thinking import (
+        DEFAULT_TOP_P, DEFAULT_TOP_K, DEFAULT_PRESENCE_PENALTY,
+        DEFAULT_REPETITION_PENALTY,
+    )
+    if model:
+        span.set_attribute("model", model)
+    span.set_attribute("temp", temp)
+    span.set_attribute("top_p", DEFAULT_TOP_P)
+    span.set_attribute("top_k", DEFAULT_TOP_K)
+    span.set_attribute("presence_penalty", DEFAULT_PRESENCE_PENALTY)
+    span.set_attribute("repetition_penalty", DEFAULT_REPETITION_PENALTY)
+    span.set_attribute("thinking_budget", thinking_budget)
+    span.set_attribute("enable_thinking", enable_thinking)
+    span.set_attribute("max_tokens", max_tokens)
+    span.set_attribute("budget_forced", budget_forced)
+
+
+def record_fsm_params(
+    span,
+    *,
+    temp: float,
+    max_tokens: int,
+    schema: str,
+    model: str = "",
+) -> None:
+    """Stamp the ACTUAL decoding config for one FSM (grammar-constrained) JSON call.
+
+    The FSM path (:mod:`agents.structured`) decodes against an outlines logits
+    processor compiled from ``schema`` and samples among the grammar-legal tokens with
+    ``temp`` / ``top_p`` / ``top_k`` (via ``make_sampler``). It runs with thinking OFF
+    and — unlike the thinking path — applies NO presence/repetition penalty (outlines
+    owns ``logits_processors``). This recorder reflects only what is genuinely applied,
+    so the trace never advertises phantom penalties or a thinking budget that don't
+    exist on these calls. Use it (not :func:`record_gen_params`) for the FSM endpoints.
+    """
+    from agents.thinking import DEFAULT_TOP_P, DEFAULT_TOP_K
+
+    if model:
+        span.set_attribute("model", model)
+    span.set_attribute("decoding", "fsm")            # grammar-constrained (outlines)
+    span.set_attribute("grammar_constrained", True)
+    span.set_attribute("fsm_schema", schema)         # the Pydantic output schema enforced
+    span.set_attribute("enable_thinking", False)     # thinking is off for FSM JSON calls
+    span.set_attribute("temp", temp)
+    span.set_attribute("top_p", DEFAULT_TOP_P)
+    span.set_attribute("top_k", DEFAULT_TOP_K)
+    span.set_attribute("max_tokens", max_tokens)
+
+
+def record_llm_io(
+    tracer,
+    prefix: str,
+    *,
+    system_prompt: str,
+    llm_input: str,
+    llm_output: str,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    think_tokens: Optional[int] = None,
+    max_input_chars: int = 8000,
+    max_output_chars: int = 8000,
+) -> None:
+    """Emit the three `<prefix>.prompt` / `.input` / `.output` child spans that
+    OpenObserve renders as dedicated Prompt / Input / Output panels.
+
+    This is the same shape the ``activity_report`` endpoint uses, so every LLM
+    call in the worklog trace (classify / propose / generate) is debuggable the
+    same way: the exact system prompt, the exact user content, and the raw model
+    output — plus token counts on the output span. Call this INSIDE the call's
+    main span so the three land as its children.
+    """
+    with tracer.start_as_current_span(f"{prefix}.prompt") as sp:
+        sp.set_attribute("total_chars", len(system_prompt or ""))
+        sp.set_attribute("llm_input", preview(system_prompt, max_chars=max_input_chars))
+    with tracer.start_as_current_span(f"{prefix}.input") as sp:
+        sp.set_attribute("total_chars", len(llm_input or ""))
+        sp.set_attribute("llm_input", preview(llm_input, max_chars=max_input_chars))
+    with tracer.start_as_current_span(f"{prefix}.output") as sp:
+        sp.set_attribute("total_chars", len(llm_output or ""))
+        sp.set_attribute("llm_output", preview(llm_output, max_chars=max_output_chars))
+        if input_tokens is not None:
+            sp.set_attribute("input_tokens", input_tokens)
+        if output_tokens is not None:
+            sp.set_attribute("output_tokens", output_tokens)
+        if think_tokens is not None:
+            sp.set_attribute("think_tokens", think_tokens)
+
+
+__all__ = [
+    "setup",
+    "extract_parent_context",
+    "setup_agno_tracing",
+    "current_traceparent",
+    "preview",
+    "record_gen_params",
+    "record_fsm_params",
+    "record_llm_io",
+]