pythinker-code 2.2.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

pythinker_code/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 2.3.0 (2026-05-09)
+
+Telemetry & observability audit.
+
+- New `pythinker_code/telemetry/errors.py` helper `report_handled_error(exc, *, site, tool=None, **attrs)` forwards caught-and-rendered exceptions to both Sentry/Bugsink and the OTel `error` event stream. Both forwarding paths are `contextlib.suppress`-wrapped so monitoring can never break the host program.
+- 38 silent-catch sites instrumented across `tools/`, `auth/`, `soul/`, `acp/`, `hooks/`, `subagents/`. Tool failures, OAuth errors, MCP server hiccups, hook callback failures, and subagent crashes now reach Bugsink and SigNoz.
+- `pythinker_code/telemetry/otel.py`: TracerProvider now uses `ParentBased(TraceIdRatioBased(rate))` driven by `PYTHINKER_OTEL_TRACE_SAMPLE_RATE` (default 1.0).
+- New `pythinker.mcp.call` span around every MCPTool RPC.
+- New `/report-error` slash command (aliases `/report`, `/report-error`).
+- `docs/en/reference/telemetry.md` documents the full telemetry contract.
+- `chore(test)`: updated google-genai snapshot for pydantic 2.13.4 + google-genai 2.0.0.
+
+
+## 2.2.1 (2026-05-09)
+
+CI hardening: macOS binary build is now optional-codesign.
+
+- `.github/workflows/release-pythinker-cli.yml`: detect whether `APPLE_CERTIFICATE_P12` and `APPLE_NOTARIZATION_KEY_P8` repo secrets are configured. When they aren't, skip the keychain setup, codesign, and notarization steps and ship an ad-hoc-signed PyInstaller binary instead of failing the whole release. The 2.2.0 release run failed because those secrets were empty in CI; this makes the release matrix all-green even without an Apple Developer cert.
+- `.github/workflows/release-pythinker-cli.yml`: add `skip-existing: true` to `pypa/gh-action-pypi-publish` so re-runs of the release workflow against an already-published version are no-ops instead of HTTP 400 errors.
+- macOS-arm64 binary downloads from the GitHub Release page will now show a Gatekeeper warning on first launch when the secrets aren't configured. Users can clear it with `xattr -d com.apple.quarantine ./pythinker`. PyPI install (`pip install pythinker-code`) is unaffected.
+
 ## 2.2.0 (2026-05-09)
 
 Installer UX: animated logo + Windows PATH automation.

pythinker_code/acp/host.py

@@ -148,6 +148,9 @@ class ACPProcess:
             )
             self._feed_output(final_output)
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="acp.host.terminal")
             error_note = f"[acp terminal error] {exc}\n"
             self._stdout.feed_data(error_note.encode("utf-8", "replace"))
             if exit_code is None:

pythinker_code/acp/session.py

@@ -233,6 +233,9 @@ class ACPSession:
             logger.info("Prompt cancelled by user")
             return acp.PromptResponse(stop_reason="cancelled")
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="acp.session.prompt")
             logger.exception("Unexpected error during prompt:")
             raise acp.RequestError.internal_error({"error": str(e)}) from e
         finally:
@@ -461,7 +464,10 @@ class ACPSession:
                 # cancelled
                 logger.debug("Permission request cancelled for: {action}", action=request.action)
                 request.resolve("reject")
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="acp.session.approval")
             logger.exception("Error handling approval request:")
             # On error, reject the request
             request.resolve("reject")

pythinker_code/auth/oauth.py

@@ -358,6 +358,9 @@ def _load_from_keyring(key: str) -> OAuthToken | None:
     try:
         raw = keyring.get_password(KEYRING_SERVICE, key)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.keyring.read")
         logger.warning("Failed to read token from keyring: {error}", error=exc)
         return None
     if not raw:
@@ -632,6 +635,9 @@ async def login_pythinker_code(
         try:
             auth = await request_device_authorization()
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.oauth.device_authorize")
             yield OAuthEvent("error", f"Login failed: {exc}")
             return
 
@@ -680,6 +686,9 @@ async def login_pythinker_code(
             yield OAuthEvent("info", "Device code expired, restarting login...")
             continue
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.oauth.device_poll")
             yield OAuthEvent("error", f"Login failed: {exc}")
             return
         break
@@ -692,6 +701,9 @@ async def login_pythinker_code(
     try:
         models = await list_models(platform, token.access_token)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.models.fetch")
         logger.error("Failed to get models: {error}", error=exc)
         yield OAuthEvent("error", f"Failed to get models: {exc}")
         return
@@ -947,6 +959,9 @@ class OAuthManager:
                     try:
                         await self.ensure_fresh(runtime, force=force)
                     except Exception as exc:
+                        from pythinker_code.telemetry.errors import report_handled_error
+
+                        report_handled_error(exc, site="auth.oauth.refresh.background")
                         logger.warning(
                             "Failed to refresh OAuth token in background: {error}",
                             error=exc,
@@ -1071,6 +1086,9 @@ class OAuthManager:
                 except Exception as exc:
                     if force:
                         raise
+                    from pythinker_code.telemetry.errors import report_handled_error
+
+                    report_handled_error(exc, site="auth.oauth.refresh")
                     logger.warning("Failed to refresh OAuth token: {error}", error=exc)
                     from pythinker_code.telemetry import track
 

pythinker_code/auth/openai.py

@@ -612,6 +612,9 @@ async def _finish_chatgpt_login(
         models = await _discover_chatgpt_models(token.access_token)
         selected_model, thinking = _select_default_openai_model(models)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.discover_chatgpt_models")
         yield OAuthEvent("error", f"Failed to discover OpenAI ChatGPT models: {exc}")
         return
 
@@ -649,6 +652,9 @@ async def login_openai_browser(
         code, verifier, redirect_uri = await _wait_for_browser_code(open_browser=open_browser)
         token_payload = await _exchange_code_for_tokens(code, verifier, redirect_uri)
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.browser_login")
         yield OAuthEvent("error", f"OpenAI browser login failed: {exc}")
         return
 
@@ -667,6 +673,9 @@ async def login_openai_headless(config: Config) -> AsyncIterator[OAuthEvent]:
     try:
         device_code = await _request_device_code()
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.device_start")
         yield OAuthEvent("error", f"Failed to start OpenAI device login: {exc}")
         return
 
@@ -688,6 +697,9 @@ async def login_openai_headless(config: Config) -> AsyncIterator[OAuthEvent]:
             OPENAI_DEVICE_REDIRECT_URI,
         )
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="auth.openai.device_poll")
         yield OAuthEvent("error", f"OpenAI device login failed: {exc}")
         return
 

pythinker_code/auth/platforms.py

@@ -248,6 +248,9 @@ async def refresh_managed_models(config: Config) -> bool:
             try:
                 await oauth_manager.ensure_fresh()
             except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(exc, site="auth.platforms.refresh.pre_sync")
                 logger.warning(
                     "Failed to refresh OAuth token before model sync for {platform}: {error}",
                     platform=platform_id,
@@ -281,6 +284,9 @@ async def refresh_managed_models(config: Config) -> bool:
             try:
                 await oauth_manager.ensure_fresh(force=True)
             except Exception as exc2:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(exc2, site="auth.platforms.refresh.after_401")
                 refresh_exc = exc2
                 logger.warning(
                     "Failed to refresh OAuth token after 401 for {platform}: {error}",
@@ -323,6 +329,9 @@ async def refresh_managed_models(config: Config) -> bool:
                         changed = True
                 continue
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="auth.platforms.sync")
             fallback_models = _fallback_or_log(platform_id=platform_id, error=exc)
             if fallback_models is None:
                 continue

pythinker_code/hooks/engine.py

@@ -237,7 +237,10 @@ class HookEngine:
             results = await self._execute_hooks(
                 event, matcher_value, server_matched, wire_matched, input_data
             )
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="hooks.engine.run")
             logger.warning("Hook engine error for {}, failing open", event)
             return []
 
@@ -278,6 +281,9 @@ class HookEngine:
             try:
                 self._on_triggered(event, matcher_value, total)
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="hooks.engine.triggered_cb")
                 logger.warning(
                     "HookTriggered callback failed for {event}: {error}, continuing",
                     event=event,
@@ -328,6 +334,9 @@ class HookEngine:
             try:
                 self._on_resolved(event, matcher_value, action, reason, duration_ms)
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="hooks.engine.resolved_cb")
                 logger.warning(
                     "HookResolved callback failed for {event}: {error}, continuing",
                     event=event,
@@ -366,6 +375,9 @@ class HookEngine:
             logger.warning("Wire hook timed out: {} {}", event, target)
             return HookResult(action="allow", timed_out=True)
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="hooks.engine.wire")
             hook_task.cancel()
             logger.warning("Wire hook failed: {} {}: {}", event, target, e)
             return HookResult(action="allow")

pythinker_code/hooks/runner.py

@@ -51,6 +51,9 @@ async def run_hook(
             await proc.wait()
             raise
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="hooks.runner")
         logger.warning("Hook failed: {}: {}", command, e)
         return HookResult(action="allow", stderr=str(e))
 

pythinker_code/soul/btw.py

@@ -176,6 +176,9 @@ async def execute_side_question(
 
         return None, "No response received."
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="soul.btw.execute")
         logger.warning("Side question failed: {error}", error=e)
         return None, str(e)
 
@@ -210,5 +213,8 @@ async def run_side_question(soul: PythinkerSoul, question: str) -> None:
         else:
             wire_send(BtwEnd(id=btw_id, error=error or "No response received."))
     except Exception as e:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(e, site="soul.btw.run_wire")
         logger.warning("Side question failed: {error}", error=e)
         wire_send(BtwEnd(id=btw_id, error=str(e)))

pythinker_code/soul/pythinkersoul.py

@@ -286,7 +286,14 @@ class PythinkerSoul:
             try:
                 result = await provider.get_injections(self._context.history, self)
                 injections.extend(result)
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.get",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s failed",
                     type(provider).__name__,
@@ -304,7 +311,14 @@ class PythinkerSoul:
         for provider in self._injection_providers:
             try:
                 await provider.on_context_compacted()
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.on_context_compacted",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s on_context_compacted failed",
                     type(provider).__name__,
@@ -316,7 +330,14 @@ class PythinkerSoul:
         for provider in self._injection_providers:
             try:
                 await provider.on_auto_changed(enabled)
-            except Exception:
+            except Exception as exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(
+                    exc,
+                    site="soul.injection.on_auto_changed",
+                    provider=type(provider).__name__,
+                )
                 logger.warning(
                     "injection provider %s on_auto_changed failed",
                     type(provider).__name__,
@@ -937,6 +958,9 @@ class PythinkerSoul:
                     try:
                         await self.compact_context()
                     except Exception as compact_err:
+                        from pythinker_code.telemetry.errors import report_handled_error
+
+                        report_handled_error(compact_err, site="soul.context.compact")
                         logger.error(
                             "Context compaction failed at step {step_no}: {error_type}: {error}",
                             step_no=step_no,
@@ -952,6 +976,9 @@ class PythinkerSoul:
             except BackToTheFuture as e:
                 back_to_the_future = e
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="soul.step.error")
                 # any other exception should interrupt the step
                 req_id = getattr(e, "request_id", None)
                 logger.error(
@@ -1453,7 +1480,10 @@ class PythinkerSoul:
                 raise
             try:
                 recovered = chat_provider.on_retryable_error(error)
-            except Exception:
+            except Exception as recover_exc:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(recover_exc, site="soul.chat.recover")
                 logger.exception(
                     "Failed to recover chat provider during {name} after {error_type}.",
                     name=name,

pythinker_code/soul/toolset.py

@@ -319,6 +319,9 @@ class PythinkerToolset:
                 parameters=parameters,
             )
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="soul.toolset.register_external")
             return False, str(e)
         self.add(tool)
         return True, None
@@ -490,6 +493,9 @@ class PythinkerToolset:
                 logger.info("Connected MCP server: {server_name}", server_name=server_name)
                 return server_name, None
             except Exception as e:
+                from pythinker_code.telemetry.errors import report_handled_error
+
+                report_handled_error(e, site="soul.toolset.mcp.connect")
                 logger.error(
                     "Failed to connect MCP server: {server_name}, error: {error}",
                     server_name=server_name,
@@ -608,6 +614,7 @@ class MCPTool[T: ClientTransport](CallableTool):
             **kwargs,
         )
         self._mcp_tool = mcp_tool
+        self._mcp_server_name = server_name
         self._client = client
         self._runtime = runtime
         self._timeout = timedelta(milliseconds=runtime.config.mcp.client.tool_call_timeout_ms)
@@ -619,25 +626,43 @@ class MCPTool[T: ClientTransport](CallableTool):
         if not result:
             return result.rejection_error()
 
+        from pythinker_code.telemetry import otel as _otel
+
+        # `start_span` returns a sync context manager (the OTel SDK uses
+        # `_AgnosticContextManager`, which intentionally has no __aenter__).
+        # Keep it as a sync `with` and use `async with` only on the fastmcp
+        # client.
         try:
-            async with self._client as client:
-                result = await client.call_tool(
-                    self._mcp_tool.name,
-                    kwargs,
-                    timeout=self._timeout,
-                    raise_on_error=False,
-                )
-                if result.is_error:
-                    logger.warning(
-                        "MCP tool returned error: {tool_name}: {content}",
-                        tool_name=self._mcp_tool.name,
-                        content=[str(p) for p in result.content][:3],
+            with _otel.start_span(
+                "pythinker.mcp.call",
+                {
+                    "mcp.server": self._mcp_server_name,
+                    "mcp.tool": self._mcp_tool.name,
+                    "mcp.timeout_ms": int(self._timeout.total_seconds() * 1000),
+                },
+            ) as span:
+                async with self._client as client:
+                    result = await client.call_tool(
+                        self._mcp_tool.name,
+                        kwargs,
+                        timeout=self._timeout,
+                        raise_on_error=False,
                     )
-                return convert_mcp_tool_result(result)
+                    span.set_attribute("mcp.is_error", bool(result.is_error))
+                    if result.is_error:
+                        logger.warning(
+                            "MCP tool returned error: {tool_name}: {content}",
+                            tool_name=self._mcp_tool.name,
+                            content=[str(p) for p in result.content][:3],
+                        )
+                    return convert_mcp_tool_result(result)
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
             # fastmcp raises `RuntimeError` on timeout and we cannot tell it from other errors
             exc_msg = str(e).lower()
             if "timeout" in exc_msg or "timed out" in exc_msg:
+                report_handled_error(e, site="soul.toolset.mcp.call.timeout", tool="MCP")
                 logger.warning(
                     "MCP tool call timed out: {tool_name}: {error}",
                     tool_name=self._mcp_tool.name,
@@ -650,6 +675,7 @@ class MCPTool[T: ClientTransport](CallableTool):
                     ),
                     brief="Timeout",
                 )
+            report_handled_error(e, site="soul.toolset.mcp.call", tool="MCP")
             logger.error(
                 "MCP tool call failed: {tool_name}: {error}",
                 tool_name=self._mcp_tool.name,
@@ -693,6 +719,9 @@ class WireExternalTool(CallableTool):
         except asyncio.CancelledError:
             raise
         except Exception as e:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(e, site="soul.toolset.external_tool", tool="External")
             logger.exception("External tool call failed: {tool_name}:", tool_name=self.name)
             return ToolError(
                 message=f"External tool call failed: {e}",

pythinker_code/subagents/runner.py

@@ -124,6 +124,9 @@ async def run_soul_checked(
             brief="LLM provider error",
         )
     except Exception as exc:
+        from pythinker_code.telemetry.errors import report_handled_error
+
+        report_handled_error(exc, site="subagents.run.soul")
         logger.exception("Subagent soul run failed when {phase}", phase=phase)
         return SoulRunFailure(
             message=f"Unexpected error when {phase}: {exc}",
@@ -316,7 +319,10 @@ class ForegroundSubagentRunner:
             self._store.update_instance(agent_id, status="killed")
             output_writer.stage("cancelled")
             raise RunCancelled("Subagent run was cancelled.") from exc
-        except Exception:
+        except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="subagents.run.background")
             self._store.update_instance(agent_id, status="failed")
             output_writer.stage("failed_exception")
             raise

pythinker_code/telemetry/config.py

@@ -52,3 +52,32 @@ def is_disabled() -> bool:
     Sentry and OTel emission for the process."""
     raw = os.environ.get("PYTHINKER_DISABLE_TELEMETRY", "").strip().lower()
     return raw in {"1", "true", "yes", "on"}
+
+
+# ---------------------------------------------------------------------------
+# Sampling
+# ---------------------------------------------------------------------------
+
+DEFAULT_OTEL_TRACE_SAMPLE_RATE = 1.0
+"""Default fraction of root-trace spans to record. 1.0 = always-on; 0.0 = none."""
+
+
+def otel_trace_sample_rate() -> float:
+    """Resolve the OTel trace sampling rate.
+
+    Honors ``PYTHINKER_OTEL_TRACE_SAMPLE_RATE``. Clamped to ``[0.0, 1.0]``.
+    Malformed input falls back to the default rather than disabling tracing
+    or raising — telemetry config must never break the host program.
+    """
+    raw = os.environ.get("PYTHINKER_OTEL_TRACE_SAMPLE_RATE", "").strip()
+    if not raw:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    try:
+        rate = float(raw)
+    except ValueError:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    if rate < 0.0:
+        return 0.0
+    if rate > 1.0:
+        return 1.0
+    return rate

pythinker_code/telemetry/errors.py

@@ -0,0 +1,107 @@
+"""Helper for reporting handled exceptions to Sentry/Bugsink + OTel.
+
+Use this at any except-block site that intentionally turns an exception into
+a graceful user-facing error result (a ``ToolError``, a TUI message, a logged
+warning). The site keeps its existing failure-rendering behaviour; the helper
+additionally informs the monitoring stack so dashboards can see the failure
+rate, class, and bucket.
+
+Privacy posture
+---------------
+Only pass primitive enum-like attributes through ``**attrs`` (tool name,
+class names, mode flags). The OTel ``error`` event is forwarded verbatim, so
+**never** pass user input, file paths, or code snippets there. Sentry is fine
+with full exception data — its ``before_send`` hook already scrubs paths and
+strips PII before transmission.
+
+Both forwarding paths are wrapped in :func:`contextlib.suppress` because
+telemetry must never break the host program.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+from pythinker_code.telemetry import sentry as _sentry
+from pythinker_code.telemetry import track
+
+# ---------------------------------------------------------------------------
+# Process-local ring buffer of recent errors
+# ---------------------------------------------------------------------------
+# Keeps just enough metadata to populate the ``/report-error`` slash command
+# without retaining the full exception object (which can hold large frames
+# and references). Class name + a short, redacted message is what shows in
+# the buffer; the *full* scrubbed stack is already in Sentry/Bugsink.
+
+_RECENT_BUFFER_SIZE = 10
+
+
+@dataclass(frozen=True, slots=True)
+class RecentError:
+    timestamp: float
+    site: str
+    exc_class: str
+    message: str  # truncated to 200 chars
+    tool: str | None
+
+
+_recent: deque[RecentError] = deque(maxlen=_RECENT_BUFFER_SIZE)
+
+
+def recent_errors() -> list[RecentError]:
+    """Snapshot of the most-recent reported errors (oldest first)."""
+    return list(_recent)
+
+
+def clear_recent_errors() -> None:
+    """Drop the recent-errors buffer. Used by tests and by ``/report-error``
+    after a successful submission."""
+    _recent.clear()
+
+
+def report_handled_error(
+    exc: BaseException,
+    *,
+    site: str,
+    tool: str | None = None,
+    **attrs: bool | int | float | str | None,
+) -> None:
+    """Forward a caught-and-rendered exception to Sentry + the OTel error stream.
+
+    Args:
+        exc: The exception that was caught at the call site.
+        site: Stable identifier for the catch site, e.g. ``"tool.read"`` or
+            ``"auth.oauth.refresh"``. Used to bucket failures in dashboards.
+            Must be a stable enum-like string, not a free-form message.
+        tool: Optional tool name when the site is a tool implementation
+            (e.g. ``"ReadFile"``). Forwarded as a separate property so SigNoz
+            queries can group by tool without parsing ``site``.
+        **attrs: Additional primitive enum-like attributes. Booleans, numbers
+            and short strings only. Values must not contain user input,
+            absolute paths, or code snippets.
+    """
+    properties: dict[str, Any] = {
+        "site": site,
+        "exc_class": type(exc).__name__,
+    }
+    if tool is not None:
+        properties["tool"] = tool
+    properties.update(attrs)
+    with contextlib.suppress(Exception):
+        track("error", **properties)
+    with contextlib.suppress(Exception):
+        _sentry.capture_exception(exc)
+    with contextlib.suppress(Exception):
+        _recent.append(
+            RecentError(
+                timestamp=time.time(),
+                site=site,
+                exc_class=type(exc).__name__,
+                message=str(exc)[:200],
+                tool=tool,
+            )
+        )

pythinker_code/telemetry/otel.py

@@ -36,9 +36,21 @@ from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import (
+    ALWAYS_OFF,
+    ALWAYS_ON,
+    ParentBased,
+    Sampler,
+    TraceIdRatioBased,
+)
 from opentelemetry.trace import Tracer
 
-from pythinker_code.telemetry.config import is_disabled, otel_endpoint, otel_ingest_token
+from pythinker_code.telemetry.config import (
+    is_disabled,
+    otel_endpoint,
+    otel_ingest_token,
+    otel_trace_sample_rate,
+)
 
 _TRACER_NAME = "pythinker-code"
 _initialized: bool = False
@@ -97,7 +109,17 @@ def init(
         headers=headers,
         timeout=10,
     )
-    tracer_provider = TracerProvider(resource=resource)
+    rate = otel_trace_sample_rate()
+    sampler: Sampler
+    if rate >= 1.0:
+        sampler = ALWAYS_ON
+    elif rate <= 0.0:
+        sampler = ALWAYS_OFF
+    else:
+        # ParentBased honors a parent's sampling decision (e.g. an upstream
+        # ACP/wire request). For root spans the ratio sampler decides.
+        sampler = ParentBased(root=TraceIdRatioBased(rate))
+    tracer_provider = TracerProvider(resource=resource, sampler=sampler)
     tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
     trace.set_tracer_provider(tracer_provider)
     _tracer = tracer_provider.get_tracer(_TRACER_NAME, version)

pythinker_code/tools/agent/__init__.py

@@ -157,6 +157,9 @@ class AgentTool(CallableTool2[Params]):
             logger.exception("Foreground agent run failed")
             return ToolError(message=f"Failed to run agent: {exc}", brief="Agent failed")
         except Exception as exc:
+            from pythinker_code.telemetry.errors import report_handled_error
+
+            report_handled_error(exc, site="tool.agent.foreground", tool="Agent")
             logger.exception("Foreground agent run failed")
             return ToolError(message=f"Failed to run agent: {exc}", brief="Agent failed")