agent-tracegraph 0.6.0__tar.gz → 0.7.0__tar.gz

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/CHANGELOG.md

@@ -6,6 +6,70 @@ The **artifact** schema version and the **report**/**review-candidate** JSON sch
 separate contracts from this version number; changes to any of them are called out
 explicitly.
 
+## 0.7.0 - 2026-10-20
+
+### Added
+
+- **`--redact-errors` on `ingest-otlp` and `ingest`** (#125) leaves error messages out of the
+  artifact. The OTLP and LangGraph adapters record the producer's error text by default
+  (`status.message` and exception events; the error channel's value and a raised exception's
+  `repr`), and `inspect` and `explain` print it; until now only Phoenix ingestion could drop it.
+  With the flag a failed step keeps its `error` status and lists `error_msg` in
+  `unknown_fields`, and nothing else in the artifact changes. A rule that reads the message
+  therefore treats it as unknown, not absent: `check --rule pattern-not-increased:timeout` reports
+  `INSUFFICIENT_EVIDENCE` for a redacted current run, and against a redacted baseline it can still
+  pass but not fail. Names are still recorded as given. The default is unchanged. In Python,
+  `LangGraphCheckpointAdapter` and `ingest_snapshot` take `include_error_messages=False`, as
+  `OTLPSpanAdapter` already did.
+
+### Changed
+
+- **`phoenix diagnose` exits 1, not 2, when `px` is unavailable or its answer cannot be used**
+  (#122). That covers a `px` that is missing or cannot run, fails, times out, prints too much,
+  prints output that is not UTF-8 or not valid JSON, reports no recognizable version or one
+  older than the supported floor, or returns an export tracegraph cannot read, and a project
+  with no traces. The command now
+  prints `FAIL <reason>` on stderr, as `phoenix doctor` does, instead of the usage banner.
+  `diagnose` used 2 for these, the same code as an invalid invocation, so a wrapper could not
+  tell "called wrong" from "Phoenix is not reachable". Some exports 0.6.1 accepted are now refused
+  as unreadable, so `diagnose` goes from 0 to 1 on them; see the Phoenix time fix below. 2 still
+  means invalid arguments or output paths, such as `--limit 0`, two outputs naming the same file,
+  or a destination that cannot be written. `doctor` is unchanged.
+
+### Fixed
+
+- **A Phoenix time given as a number too small to be epoch nanoseconds is no longer read as one**
+  (#124). The Phoenix adapter took every numeric `start_time` / `end_time` as nanoseconds, so a
+  time in seconds, milliseconds or microseconds became a moment near 1970, with its sub-unit
+  digits truncated and no warning: a 500 ms span given in float seconds was recorded at
+  `1970-01-01T00:00:01.783987+00:00` with a duration of 0.0. A number is now read as nanoseconds
+  only from 10^17 (1973-03-03T09:46:40Z) up. Below that, seconds, milliseconds and microseconds
+  for any date before the year 5138 cannot be told apart, so the time is reported as unavailable
+  and disclosed as `otlp.unreadable_timestamp`, the code an unreadable time already uses, which
+  0.6.x readers know. That applies to numbers, digit strings, and strings `int()` reads with a
+  sign, surrounding whitespace or underscores. ISO strings are read as before, including compact
+  forms such as `20260714_123456`, and so are nanosecond values. Phoenix's own `trace get` export
+  uses ISO strings, so artifacts change only for exports that carried such numbers.
+
+  For an export that carries such numbers, the step sequence, the parent chosen among several
+  spans sharing a `graph.node.id`, and whether the export is accepted at all can also differ from
+  0.6.1, which read the numbers as nanoseconds and ordered spans by them. For example, take spans
+  `a` and `b` with `graph.node.id` `loop`, starting at 1783987200 and 1783987201, and a span `c`
+  starting at 1783987202 with `graph.node.parent_id` `loop` and no `parent_id`. 0.6.1 took `b` as
+  `c`'s parent and exited 0; now `ingest-phoenix` and `analyze` exit 2 and `phoenix diagnose`
+  exits 1.
+
+## 0.6.1 - 2026-10-20
+
+### Dependencies
+
+- `langgraph-checkpoint-sqlite` now requires `>=3.1.1` (was `>=2`), the first release with the
+  fix for GHSA-47pj-3jcm-6whg, where store namespace prefixes could match across segment
+  boundaries. Tracegraph reads checkpoints through `SqliteSaver` and never uses the store; the
+  floor keeps an install from resolving a flagged version. The source, commands and JSON
+  contracts are the same as 0.6.0, but the install range is narrower: an environment that pins
+  `langgraph-checkpoint-sqlite==3.1.0` resolves with 0.6.0 and not with 0.6.1.
+
 ## 0.6.0 - 2026-10-20
 
 ### Added

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tracegraph
-Version: 0.6.0
+Version: 0.7.0
 Summary: Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph.
 Project-URL: Homepage, https://github.com/memtomem/tracegraph
 Project-URL: Repository, https://github.com/memtomem/tracegraph
@@ -19,7 +19,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Debuggers
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: langgraph-checkpoint-sqlite>=2
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1.1
 Requires-Dist: langgraph-checkpoint>=4.1
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: rich>=13
@@ -201,8 +201,9 @@ trace. If none failed, it says so and diagnoses the newest trace, so a first suc
 still useful. Explicit ids bypass that selection. The command invokes only read-only
 `px trace list/get --include-annotations` exports, analyzes them in memory, and does not persist
 the raw Phoenix response. Phoenix connection details and credentials remain owned by `px`
-profiles or environment variables; tracegraph never accepts an API key option. For an already
-exported file or a shell pipeline:
+profiles or environment variables; tracegraph never accepts an API key option. Both commands exit
+1 when `px` is missing, cannot run, or returns a response tracegraph cannot use, and 2 for
+invalid arguments or output paths. For an already exported file or a shell pipeline:
 
 Automatic retry diagnosis intentionally requires an upstream `retry:` CHAIN marker. SyncMill's
 controlled retry telemetry emits this contract; generic OTLP and LangGraph-checkpoint producers
@@ -237,8 +238,11 @@ identifiers, and credentials. Missing metrics are reported as `unavailable`, nev
 (identifier-shaped span names only, error messages dropped), but the OTLP and LangGraph
 adapters record the span name and error text they were given: OTLP keeps `status.message`
 and exception messages, and LangGraph stringifies the configured error state channel. Those
-values reach the artifact on disk and are printed verbatim by `inspect` and `explain`. If
-your producer puts prompt text or secrets in span names or error strings, treat artifacts
+values reach the artifact on disk and are printed verbatim by `inspect` and `explain`.
+`ingest-otlp --redact-errors` and `ingest --redact-errors` leave the error text out: a failed
+step keeps its `error` status and lists `error_msg` in `unknown_fields`, so a rule that reads
+the message (the `timeout` preset) reports it as unknown rather than absent. Names are still
+recorded as given. If your producer puts prompt text or secrets in span names, treat artifacts
 from those two adapters as sensitive, or ingest through Phoenix. See "Analysis and output
 guarantees" below.
 
@@ -253,14 +257,16 @@ tracegraph analyze full-dag.json
 ```
 
 `analyze` reads an OTLP span export (JSON or Collector JSONL) directly, with the same adapter
-settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact;
+settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact
+(one ingested with `--redact-errors` can differ where a rule reads the message);
 nothing is written unless `--json-out` asks for a report. The input is identified by shape alone
 (`schema_version` → artifact, `resourceSpans` → OTLP, `spans`/`traces`/`data` → Phoenix); a
 payload carrying both OTLP and Phoenix records is refused, naming the explicit ingest command
 for each format (or, for a list, JSONL or envelope, asking you to extract one format's records). Already have an export? The shortest offline first run is
 `tracegraph analyze your-export.otlp.json` (add `--trace <id>` when the file holds several), then
 copy the `explain` command it prints after saving the artifact it names. The artifact caveat
-above still applies: `ingest-otlp` keeps error text, reports stay `safe-v1`.
+above still applies: `ingest-otlp` keeps error text unless given `--redact-errors`, and
+reports stay `safe-v1`.
 
 The JSON analysis-report contract is versioned at
 [`contracts/analysis-report.schema.json`](contracts/analysis-report.schema.json).
@@ -391,7 +397,7 @@ Known limits:
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
-  producer's names and error messages.
+  producer's names, and its error messages unless ingested with `--redact-errors`.
 - CI covers Python 3.12 on Linux.
 
 Caveat for the checkpoint adapter: it is a **checkpoint-level** view (one node per
@@ -437,7 +443,8 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+error message (`--redact-errors` on `ingest` and `ingest-otlp` drops the message, not the
+name). Phoenix ingestion is the exception: it filters at the source, keeping span
 names and annotation names and labels only when they are identifier-shaped, and dropping
 status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/README.md

@@ -170,8 +170,9 @@ trace. If none failed, it says so and diagnoses the newest trace, so a first suc
 still useful. Explicit ids bypass that selection. The command invokes only read-only
 `px trace list/get --include-annotations` exports, analyzes them in memory, and does not persist
 the raw Phoenix response. Phoenix connection details and credentials remain owned by `px`
-profiles or environment variables; tracegraph never accepts an API key option. For an already
-exported file or a shell pipeline:
+profiles or environment variables; tracegraph never accepts an API key option. Both commands exit
+1 when `px` is missing, cannot run, or returns a response tracegraph cannot use, and 2 for
+invalid arguments or output paths. For an already exported file or a shell pipeline:
 
 Automatic retry diagnosis intentionally requires an upstream `retry:` CHAIN marker. SyncMill's
 controlled retry telemetry emits this contract; generic OTLP and LangGraph-checkpoint producers
@@ -206,8 +207,11 @@ identifiers, and credentials. Missing metrics are reported as `unavailable`, nev
 (identifier-shaped span names only, error messages dropped), but the OTLP and LangGraph
 adapters record the span name and error text they were given: OTLP keeps `status.message`
 and exception messages, and LangGraph stringifies the configured error state channel. Those
-values reach the artifact on disk and are printed verbatim by `inspect` and `explain`. If
-your producer puts prompt text or secrets in span names or error strings, treat artifacts
+values reach the artifact on disk and are printed verbatim by `inspect` and `explain`.
+`ingest-otlp --redact-errors` and `ingest --redact-errors` leave the error text out: a failed
+step keeps its `error` status and lists `error_msg` in `unknown_fields`, so a rule that reads
+the message (the `timeout` preset) reports it as unknown rather than absent. Names are still
+recorded as given. If your producer puts prompt text or secrets in span names, treat artifacts
 from those two adapters as sensitive, or ingest through Phoenix. See "Analysis and output
 guarantees" below.
 
@@ -222,14 +226,16 @@ tracegraph analyze full-dag.json
 ```
 
 `analyze` reads an OTLP span export (JSON or Collector JSONL) directly, with the same adapter
-settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact;
+settings as `ingest-otlp`, so the report is byte-identical to analysing the ingested artifact
+(one ingested with `--redact-errors` can differ where a rule reads the message);
 nothing is written unless `--json-out` asks for a report. The input is identified by shape alone
 (`schema_version` → artifact, `resourceSpans` → OTLP, `spans`/`traces`/`data` → Phoenix); a
 payload carrying both OTLP and Phoenix records is refused, naming the explicit ingest command
 for each format (or, for a list, JSONL or envelope, asking you to extract one format's records). Already have an export? The shortest offline first run is
 `tracegraph analyze your-export.otlp.json` (add `--trace <id>` when the file holds several), then
 copy the `explain` command it prints after saving the artifact it names. The artifact caveat
-above still applies: `ingest-otlp` keeps error text, reports stay `safe-v1`.
+above still applies: `ingest-otlp` keeps error text unless given `--redact-errors`, and
+reports stay `safe-v1`.
 
 The JSON analysis-report contract is versioned at
 [`contracts/analysis-report.schema.json`](contracts/analysis-report.schema.json).
@@ -360,7 +366,7 @@ Known limits:
 - Phoenix exports carry no span links, so their artifacts are parent-only; additional fan-in
   causes may be missing.
 - Report privacy (`safe-v1`) applies to reports; OTLP and LangGraph artifacts keep the
-  producer's names and error messages.
+  producer's names, and its error messages unless ingested with `--redact-errors`.
 - CI covers Python 3.12 on Linux.
 
 Caveat for the checkpoint adapter: it is a **checkpoint-level** view (one node per
@@ -406,7 +412,8 @@ with deterministic SHA-256 aliases, and disclose in `warnings` when an alias act
 the report. Trace/step identifiers remain; this is not anonymization.
 Raw artifact names and bytes are not rewritten for report privacy or matching, so the
 artifact — unlike the report — can still carry whatever the producer put in a span name or
-error message. Phoenix ingestion is the exception: it filters at the source, keeping span
+error message (`--redact-errors` on `ingest` and `ingest-otlp` drops the message, not the
+name). Phoenix ingestion is the exception: it filters at the source, keeping span
 names and annotation names and labels only when they are identifier-shaped, and dropping
 status messages. Identifier-shaped is not the same as anonymous: an e-mail address passes.
 `export-review-candidates` output is not passed through the report redactor: its `tool_key`

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/SECURITY.md

@@ -42,19 +42,23 @@ prompts, inputs and outputs, tool arguments and results, raw errors and stacktra
 session/user/project identifiers. Other display text is replaced with a deterministic
 SHA-256 alias, and the report discloses in `warnings` when an alias actually reached it.
 
-The artifact on disk is a different thing. Phoenix ingestion filters at the source, but the
-OTLP and LangGraph adapters record what they were given:
+The artifact on disk is a different thing. Phoenix ingestion filters at the source, but by
+default the OTLP and LangGraph adapters record what they were given:
 
 - OTLP keeps `status.message` and exception messages;
 - LangGraph stringifies the configured error state channel, **and** the `repr` of an
   exception a node raised, which it reads from checkpoint pending writes.
 
-Those values reach the artifact and are printed verbatim by `inspect` and `explain`.
+Those values reach the artifact and are printed verbatim by `inspect` and `explain`, unless
+the trace is ingested with `--redact-errors` (`ingest-otlp` and `ingest` both take it), which
+leaves every error message out and marks it unknown on the step. Span and node names are
+recorded as given either way.
 `export-review-candidates` is likewise not passed through the report redactor: its
 `tool_key` is the raw endpoint span name.
 
 **So: if your producer puts prompt text, customer data, or credentials into span names or
-exception messages, those land in the artifact.** Treat artifacts with the same care as the
+exception messages, those land in the artifact** — the messages only when ingested without
+`--redact-errors`, the names always. Treat artifacts with the same care as the
 traces they came from. Reports, not artifacts, are the artifact you share.
 
 Identifiers are not anonymized in either form — trace and step ids are preserved by design,
@@ -64,12 +68,16 @@ because they are what makes a finding traceable back to the run.
 
 Artifact and span-export loading is a parsing boundary, not a trust boundary: input is
 validated, never executed. Malformed input raises a clean error rather than a traceback, and
-tree walks are iterative so a deeply nested document cannot exhaust the stack. **CLI inputs**,
-files named on the command line and `-` for stdin alike, are size-capped by default at 256 MiB
-(`TRACEGRAPH_MAX_ARTIFACT_BYTES` changes it, and `0` disables it). That cap is a property of
-the command-line entry points, not of the library: `artifact.load()` and
-`OTLPSpanAdapter.from_file()` read what they are given, so a library caller handling untrusted
-input should bound it themselves. Still, analyzing an artifact you did not produce means reading
+tree walks are iterative so a deeply nested document cannot exhaust the stack. **CLI JSON
+inputs** (artifacts and span exports), files named on the command line and `-` for stdin
+alike, are size-capped by default at 256 MiB (`TRACEGRAPH_MAX_ARTIFACT_BYTES` changes it, and
+`0` disables it). A LangGraph checkpoint database (`ingest --sqlite`) is not byte-capped: it
+is copied to a private snapshot under a deadline (30 seconds by default) before it is read.
+The cap is a property of the command-line entry points, not of the library:
+`artifact.load()`, `OTLPSpanAdapter.from_file()`, `PhoenixExportAdapter.from_file()`, and
+`InMemoryStore.load_artifact()` and `LadybugStore.load_artifact()` (which call
+`artifact.load()`) read what they are given, so a library caller handling untrusted input
+should bound it themselves. Still, analyzing an artifact you did not produce means reading
 strings an attacker may have chosen; render them as data.
 
 Subprocess use is limited to one call site, the Phoenix CLI (`px`), invoked as an argument

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # the schema `kind` constants and the TRACEGRAPH_* environment variables — those are package
 # identity, not distribution identity, and renaming them would break published contracts.
 name = "agent-tracegraph"
-version = "0.6.0"
+version = "0.7.0"
 description = "Time-travel debugging and causal RCA for LangGraph agent traces, on a causal graph."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,7 +30,10 @@ classifiers = [
 
 dependencies = [
     "pydantic>=2,<3",
-    "langgraph-checkpoint-sqlite>=2",
+    # 3.1.1 fixes GHSA-47pj-3jcm-6whg (store namespace prefixes crossing segment boundaries).
+    # Tracegraph reads only SqliteSaver, never the store; the floor keeps installs off the
+    # flagged versions.
+    "langgraph-checkpoint-sqlite>=3.1.1",
     # Declared directly, not left transitive, because `ingest` now calls its serializer API:
     # `JsonPlusSerializer(allowed_msgpack_modules=...)` is what stops a checkpoint payload
     # invoking arbitrary callables, and it does not exist before 4.1 (4.0.0 raises TypeError,

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/adapters/langgraph_checkpoint.py

@@ -209,6 +209,7 @@ class LangGraphCheckpointAdapter:
         error_channel: str = "error",
         source_kind: str = "langgraph",
         schedule_graph: Any = None,
+        include_error_messages: bool = True,
     ) -> None:
         self._saver = saver
         self._error_channel = error_channel
@@ -216,6 +217,9 @@ class LangGraphCheckpointAdapter:
         #: A compiled LangGraph graph to ask which tasks are scheduled at the head; see the
         #: module docstring. ``None`` leaves scheduled-but-unwritten tasks unreported.
         self._schedule_graph = schedule_graph
+        #: Off, a failed step keeps its ERROR status but not the error channel's value or the
+        #: exception text, and lists ``error_msg`` as unknown, as OTLP's option of that name does.
+        self._include_error_messages = include_error_messages
 
     # --- TraceAdapter ---
 
@@ -388,14 +392,18 @@ class LangGraphCheckpointAdapter:
                 rewritten_errors += self._rewrote_error(checkpoints[step_id], history)
             if err is not None:
                 step.status = StepStatus.ERROR
-                step.error_msg = err
+                if self._include_error_messages:
+                    step.error_msg = err
+                else:
+                    step.unknown_fields.insert(0, "error_msg")  # sorts before kind and name
 
         # Derived task steps come last: everything above indexes `steps` by checkpoint id
         # (`checkpoints[step_id]`, `key_by_step_id[step_id]`), and a derived id has no entry
         # in either. Building them here also means they inherit each carrying step's *final*
         # seq, after `_topo_seq` may have re-sequenced the whole thread.
         disclosures = self._derive_task_steps(
-            trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges
+            trace_id, steps, checkpoints, key_by_step_id, original_seq, writes_by_step, edges,
+            include_error_messages=self._include_error_messages,
         )
         disclosures.extend(
             self._derive_interrupt_steps(
@@ -463,6 +471,8 @@ class LangGraphCheckpointAdapter:
         original_seq: dict[str, int],
         writes_by_step: dict[str, dict[str, list[tuple[str, Any]]]],
         edges: list[Edge],
+        *,
+        include_error_messages: bool,
     ) -> Disclosures:
         """Add one ERROR step per failed task and return any ingestion disclosures.
 
@@ -506,8 +516,9 @@ class LangGraphCheckpointAdapter:
                         "in LangGraph's task-id algorithm would look like.",
                     )
                 unknown: list[UnknownField] = [] if name else ["kind", "name"]
-                if error is None and not cancelled:
-                    # _error_message's placeholder: the checkpointer kept no exception text.
+                if (error is None or not include_error_messages) and not cancelled:
+                    # _error_message's placeholder (the checkpointer kept no exception text),
+                    # or a message withheld on request.
                     unknown.insert(0, "error_msg")
                 derived_id = f"{step_id}#task:{task_id}"
                 if derived_id in steps or derived_id in derived_ids:
@@ -533,7 +544,7 @@ class LangGraphCheckpointAdapter:
                         # without claiming it failed, and leaves the trace status to the task
                         # that actually raised.
                         status=StepStatus.UNSET if cancelled else StepStatus.ERROR,
-                        error_msg=None if cancelled else message,
+                        error_msg=None if cancelled or not include_error_messages else message,
                         unknown_fields=unknown,
                     ),
                 ))

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/adapters/otlp_spans.py

@@ -423,6 +423,7 @@ class OTLPSpanAdapter:
 
     @classmethod
     def from_file(cls, path: str | Path, **kwargs: Any) -> "OTLPSpanAdapter":
+        """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
         return cls.from_json(Path(path).read_text(encoding="utf-8"), **kwargs)
 
     # --- TraceAdapter ---

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/adapters/phoenix_export.py

@@ -9,7 +9,13 @@ import re
 from typing import Any
 
 from tracegraph.adapters.base import Disclosures
-from tracegraph.adapters.otlp_spans import OTLPSpanAdapter, _attributes, _first, _span_array
+from tracegraph.adapters.otlp_spans import (
+    OTLPSpanAdapter,
+    _attributes,
+    _first,
+    _parse_nanos,
+    _span_array,
+)
 from tracegraph.input_validation import loads, object_field
 from tracegraph.model import RawTrace
 
@@ -30,22 +36,44 @@ _SAFE_ATTRIBUTES = {
 }
 
 
+#: The smallest number read as epoch nanoseconds: 1973-03-03T09:46:40Z. Seconds, milliseconds and
+#: microseconds for any date before the year 5138 all fall below it, so a smaller number is in
+#: some other unit, and which one cannot be told from its size.
+_MIN_EPOCH_NANOS = 10**17
+#: Handed on for a number below the floor. ``int()`` cannot read it, so the span builder reports
+#: the time as unavailable and counts it under ``otlp.unreadable_timestamp``. It is fixed text, so
+#: no producer code (a ``__repr__``) runs, and only the parsed time ever reaches the artifact.
+_NOT_EPOCH_NANOS = "not epoch nanoseconds"
+
+
+def _epoch_nanos(number: int) -> str:
+    return str(number) if number >= _MIN_EPOCH_NANOS else _NOT_EPOCH_NANOS
+
+
 def _nanos(value: Any) -> Any:
-    """Phoenix's time to OTLP nanoseconds. A value that cannot be converted is passed on
-    unchanged, so the span builder reports it as unavailable *and* discloses it."""
+    """Phoenix's time to OTLP nanoseconds. A value that cannot be converted, or a number too
+    small to be epoch nanoseconds, is handed on in a form the span builder cannot read, so it
+    reports the time as unavailable *and* discloses it."""
     if value is None:
         return None
     if isinstance(value, float) and not math.isfinite(value):
         return value
     if isinstance(value, (int, float)):
-        return str(int(value))
+        return _epoch_nanos(int(value))
     text = str(value)
     if text.isdigit():
-        return text
+        try:
+            return _epoch_nanos(int(text))
+        except ValueError:  # a non-ASCII digit, or past the interpreter's int-string limit
+            return text
     try:
         parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
     except ValueError:
-        return value
+        # Whatever the span builder would still read as a time (a sign, whitespace, underscores,
+        # bytes) is a number, so the floor applies to it too. Asking the builder's own parser
+        # keeps the two from disagreeing about what is a number.
+        number = _parse_nanos(value)
+        return value if number is None else _epoch_nanos(number)
     if parsed.tzinfo is None:
         parsed = parsed.replace(tzinfo=timezone.utc)
     return str(int(parsed.timestamp() * 1_000_000_000))
@@ -151,6 +179,7 @@ class PhoenixExportAdapter:
 
     @classmethod
     def from_file(cls, path: str | Path) -> "PhoenixExportAdapter":
+        """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
         return cls.from_json(Path(path).read_text(encoding="utf-8"))
 
     def discover(self) -> list[str]:

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/artifact.py

@@ -243,6 +243,7 @@ def save_atomic(nt: NormalizedTrace, path: str | Path, *, replace: bool = True)
 
 
 def load(path: str | Path) -> NormalizedTrace:
+    """Reads the whole file: the CLI's ``TRACEGRAPH_MAX_ARTIFACT_BYTES`` cap does not apply here."""
     return loads(Path(path).read_text(encoding="utf-8"))
 
 

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/cli.py

@@ -1280,6 +1280,12 @@ def _render_tree(nt: NormalizedTrace) -> None:
     )
 
 
+_REDACT_ERRORS_HELP = (
+    "Leave error messages out of the artifact: a failed step keeps its error status and "
+    "lists its message as unknown. Step names are still recorded as given."
+)
+
+
 @app.command()
 def ingest(
     sqlite: Path = typer.Option(..., help="Path to a LangGraph SqliteSaver DB file."),
@@ -1300,14 +1306,18 @@ def ingest(
             "module, and the graph's state callbacks while reading; never a node."
         ),
     ),
+    redact_errors: bool = typer.Option(False, "--redact-errors", help=_REDACT_ERRORS_HELP),
 ) -> None:
     """Ingest a LangGraph thread's checkpoint history into a portable artifact."""
     from tracegraph.sqlite_snapshot import ingest_snapshot
 
     target = out or artifact.default_path(thread)
     _distinct_paths([sqlite], [target])
-    # Passed only when given, so an ingest without --graph makes exactly the call it always has.
+    # Passed only when given, so an ingest without --graph or --redact-errors makes exactly the
+    # call it always has.
     extra: dict[str, Any] = {}
+    if redact_errors:
+        extra["include_error_messages"] = False
     if graph is not None:
         from tracegraph.graph_ref import load_graph
 
@@ -1328,6 +1338,7 @@ def ingest_otlp(
     file: str = typer.Option(..., "--file", "-f", help="OTLP JSON/JSONL span export (resourceSpans), or '-' for stdin."),
     trace: str = typer.Option(None, "--trace", "-t", help="traceId to ingest (default: the file's only trace)."),
     out: Path = typer.Option(None, "--out", "-o", help="Artifact path (default <traceId>.json)."),
+    redact_errors: bool = typer.Option(False, "--redact-errors", help=_REDACT_ERRORS_HELP),
 ) -> None:
     """Ingest one trace from an OpenInference/OTLP span export into a portable artifact."""
     from tracegraph.adapters import OTLPSpanAdapter
@@ -1336,7 +1347,9 @@ def ingest_otlp(
         # Bounded read through the common size-limited boundary (from_file would
         # read_text the whole file with no ceiling). KeyError joins the usual load
         # errors: the adapter raises it for an unknown/missing trace id.
-        adapter = OTLPSpanAdapter.from_json(_read_source(file))
+        adapter = OTLPSpanAdapter.from_json(
+            _read_source(file), include_error_messages=not redact_errors
+        )
         trace = _select_trace(adapter, trace, what="file")
         nt = _normalize_read(adapter.ingest(trace))
     except (*_LOAD_ERRORS, KeyError) as exc:
@@ -1511,7 +1524,10 @@ def phoenix_diagnose(
                 )
         baseline_nt = _px_trace(baseline, project=project) if baseline else None
     except _PxError as exc:
-        raise typer.BadParameter(str(exc)) from exc
+        # Phoenix or `px` is unavailable or answered unusably: report it as `doctor` does
+        # (exit 1), keeping 2 for an invalid invocation.
+        err_console.print(f"[bold red]FAIL[/] {escape(str(exc))}")
+        raise typer.Exit(1) from exc
     report = build_analysis(nt, baseline=baseline_nt)
     _render_analysis(report, limit=limit)
     if save_artifact:

{agent_tracegraph-0.6.0 → agent_tracegraph-0.7.0}/src/tracegraph/sqlite_snapshot.py

@@ -36,7 +36,13 @@ def _inert_serde():
 
 
 def ingest_snapshot(
-    source: Path, thread: str, *, error_channel: str, timeout: float = 30, graph: Any = None
+    source: Path,
+    thread: str,
+    *,
+    error_channel: str,
+    timeout: float = 30,
+    graph: Any = None,
+    include_error_messages: bool = True,
 ) -> RawTrace:
     from langgraph.checkpoint.sqlite import SqliteSaver
 
@@ -64,7 +70,10 @@ def ingest_snapshot(
             with closing(sqlite3.connect(str(snapshot), check_same_thread=False)) as conn:
                 saver = SqliteSaver(conn, serde=_inert_serde())
                 return LangGraphCheckpointAdapter(
-                    saver, error_channel=error_channel, schedule_graph=graph
+                    saver,
+                    error_channel=error_channel,
+                    schedule_graph=graph,
+                    include_error_messages=include_error_messages,
                 ).ingest(thread)
     except sqlite3.Error as exc:
         raise ValueError("cannot read SQLite checkpoint snapshot") from exc