tracengent 0.1.0__tar.gz

tracengent-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python build / cache artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/

tracengent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Besar Kutleshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tracengent-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: tracengent
+Version: 0.1.0
+Summary: First-party Python SDK for Tracengent: instrument and govern agents (events, decision traces, authorization, tool governance, delegation).
+Project-URL: Homepage, https://github.com/besarkutleshi/agentgov
+Project-URL: Source, https://github.com/besarkutleshi/agentgov
+Project-URL: Repository, https://github.com/besarkutleshi/agentgov.git
+Author: Besar Kutleshi
+License: MIT
+License-File: LICENSE
+Keywords: agent,authorization,governance,llm,observability,tracengent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: flask>=3.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# Tracengent — Python SDK
+
+First-party Python SDK for [Tracengent](../../phases/phase-10-multi-language-sdks.md): instrument and
+govern agents written in Python with parity to the .NET SDK ([`src/Tracengent.Sdk`](../../src/Tracengent.Sdk/)).
+
+> **Status: feature-complete (Phase 10).** Full parity with the .NET SDK across telemetry, traces,
+> authorization, tool governance, and delegation. The reference implementation is the .NET SDK; the
+> contract is [§3 of the phase doc](../../phases/phase-10-multi-language-sdks.md#3-the-shared-wire-contract-the-spec-all-five-sdks-implement).
+
+## Milestone status
+
+| Milestone | Capability | State |
+|---|---|---|
+| **M1** | Options + validation, JWT/permission helpers, JSON redactor (pure logic) | ✅ done |
+| **M2** | Event model, token provider, background dispatcher, `record` | ✅ done |
+| **M3** | Decision traces + auto-tracking + ambient context + `authorize`/`ensure_authorized` | ✅ done |
+| **M4** | `has_permission` (token-local) + framework bindings (FastAPI/Flask) | ✅ done |
+| **M5** | Tool governance: egress gate, MCP/function gate, redaction | ✅ done |
+| **M6** | Delegation: delegated session + attenuation (A2A) | ✅ done |
+| **M7** | Packaging + sample + conformance + (gated) integration tests | ✅ done |
+
+**Tests:** 152 unit + 7 conformance, 3 gated integration tests (`pytest -m integration`). The
+conformance suite replays the shared [`wire_contract.json`](tests/conformance/wire_contract.json)
+fixture and asserts the SDK's request shapes match the contract byte-for-byte (modulo volatile
+ids/timestamps) — this same fixture is vendored into every Tracengent SDK. A runnable end-to-end
+example lives in [`samples/demo_agent.py`](samples/demo_agent.py).
+
+## What works today (M1–M3)
+
+```python
+from tracengent import TracengentClient, TracengentOptions, LlmCallResult, Money
+
+opts = TracengentOptions.from_env(agent_id="travel-agent")
+with TracengentClient(opts) as client:
+    # Open a decision trace — groups steps, tool calls and actions into one timeline.
+    with client.begin_trace("book a trip to Lisbon", actor_user_id="u_123") as trace:
+        trace.step("decided to search flights")
+
+        # Wrap tool calls / actions — timed and recorded automatically.
+        flights = trace.track_tool_call("search-flights", lambda: search(...))
+
+        # Govern an LLM call: reserve token budget before, reconcile actual usage after.
+        answer = trace.track_llm_call(
+            "summarize",
+            lambda: LlmCallResult(value=call_model(...), tokens=900, model="gpt"),
+            estimated_tokens=1000,
+        )
+
+        # Imperative authorization for a sensitive action (raises if denied).
+        # Send the spend's currency too — the platform converts it into the policy/budget
+        # currency before enforcing limits, so a USD charge is checked against a EUR cap.
+        client.ensure_authorized("payments:refund", {"amount": 280, "currency": "USD"})
+        trace.track_action("refund", lambda: do_refund(...), cost=Money.eur(280))
+# leaving the trace flushes its completion; leaving the client flushes remaining events.
+```
+
+Outbound HTTP can be auto-recorded as `tool_call` events by routing it through a tracked client:
+
+```python
+from tracengent import tracked_client
+
+http = tracked_client(client, base_url="https://api.example.com")
+http.get("/things")   # recorded as a tool_call, attached to the active trace
+```
+
+Declarative gating for web-hosted agents (the equivalent of .NET's `[RequireAgentPermission]`):
+
+```python
+from fastapi import FastAPI, Depends
+from tracengent.integrations.fastapi import install_tracengent, require_agent_permission
+
+app = FastAPI()
+install_tracengent(app, client)
+
+@app.post("/refunds", dependencies=[Depends(require_agent_permission("payments:refund"))])
+def refund(): ...        # 403s automatically when the agent lacks the permission
+```
+
+A Flask decorator (`tracengent.integrations.flask`) and a token-local coarse check
+(`client.has_permission("flights:book")`, no round-trip) are also available.
+
+**Tool governance (Phase 8).** Govern outbound tool calls the org doesn't own — block, hold for
+approval, or redact before the request leaves:
+
+```python
+from tracengent import governed_client
+
+# Every request through this client is authorized via /v1/tool-authorize first.
+tools = governed_client(client, base_url="https://api.stripe.com")
+tools.post("/v1/refunds", json={"amount": 280, "card": "4242"})
+# -> denied/held → raises; allowed → forwarded with any redactions applied.
+
+# Non-HTTP tools (MCP tools/call, LLM function calls):
+client.tools.guard_function("transfer_funds", {"to": "...", "amount": 50}, invoke=do_transfer)
+```
+
+**Delegation / agent-to-agent (Phase 5).** Act under a delegated token and attenuate authority for a
+downstream agent:
+
+```python
+session = client.begin_delegated_task(delegated_token)   # token granted out of band
+session.authorize("flights:book", {"amount": 280})       # intersects base policy with the grant
+
+# Mint a narrower child token to hand to another agent for an A2A hop:
+child = session.attenuate_for_call("agt_hotel", ["hotels:book"], max_amount=500)
+```
+
+Pure helpers are also exported directly:
+
+```python
+from tracengent import permission_matches, Redaction, apply_redactions
+
+permission_matches("flights:*", "flights:book")   # True
+apply_redactions('{"amount":100,"card":"4242"}', [Redaction("$.card", "mask")])
+# -> '{"amount":100,"card":"***REDACTED***"}'
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx` (HTTP transport)
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest -q          # unit tests
+ruff check .       # lint
+mypy               # type-check
+```
+
+CI runs lint + type-check + tests on every push (see [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml), job `sdk-python`).
+
+## Environment variables
+
+| Var | Meaning |
+|---|---|
+| `TRACENGENT_URL` | Base URL of the Tracengent API |
+| `TRACENGENT_CLIENT_ID` | Agent OAuth client id (`key_...`) — preferred |
+| `TRACENGENT_CLIENT_SECRET` | Agent OAuth client secret (`ags_...`) |
+| `TRACENGENT_INGEST_KEY` | Legacy org ingest key (`agk_...`) — fallback |
+| `TRACENGENT_AGENT_ID` | Logical agent key reported with events |
+| `TRACENGENT_ENVIRONMENT` | Environment tag (default `production`) |

tracengent-0.1.0/README.md

@@ -0,0 +1,144 @@
+# Tracengent — Python SDK
+
+First-party Python SDK for [Tracengent](../../phases/phase-10-multi-language-sdks.md): instrument and
+govern agents written in Python with parity to the .NET SDK ([`src/Tracengent.Sdk`](../../src/Tracengent.Sdk/)).
+
+> **Status: feature-complete (Phase 10).** Full parity with the .NET SDK across telemetry, traces,
+> authorization, tool governance, and delegation. The reference implementation is the .NET SDK; the
+> contract is [§3 of the phase doc](../../phases/phase-10-multi-language-sdks.md#3-the-shared-wire-contract-the-spec-all-five-sdks-implement).
+
+## Milestone status
+
+| Milestone | Capability | State |
+|---|---|---|
+| **M1** | Options + validation, JWT/permission helpers, JSON redactor (pure logic) | ✅ done |
+| **M2** | Event model, token provider, background dispatcher, `record` | ✅ done |
+| **M3** | Decision traces + auto-tracking + ambient context + `authorize`/`ensure_authorized` | ✅ done |
+| **M4** | `has_permission` (token-local) + framework bindings (FastAPI/Flask) | ✅ done |
+| **M5** | Tool governance: egress gate, MCP/function gate, redaction | ✅ done |
+| **M6** | Delegation: delegated session + attenuation (A2A) | ✅ done |
+| **M7** | Packaging + sample + conformance + (gated) integration tests | ✅ done |
+
+**Tests:** 152 unit + 7 conformance, 3 gated integration tests (`pytest -m integration`). The
+conformance suite replays the shared [`wire_contract.json`](tests/conformance/wire_contract.json)
+fixture and asserts the SDK's request shapes match the contract byte-for-byte (modulo volatile
+ids/timestamps) — this same fixture is vendored into every Tracengent SDK. A runnable end-to-end
+example lives in [`samples/demo_agent.py`](samples/demo_agent.py).
+
+## What works today (M1–M3)
+
+```python
+from tracengent import TracengentClient, TracengentOptions, LlmCallResult, Money
+
+opts = TracengentOptions.from_env(agent_id="travel-agent")
+with TracengentClient(opts) as client:
+    # Open a decision trace — groups steps, tool calls and actions into one timeline.
+    with client.begin_trace("book a trip to Lisbon", actor_user_id="u_123") as trace:
+        trace.step("decided to search flights")
+
+        # Wrap tool calls / actions — timed and recorded automatically.
+        flights = trace.track_tool_call("search-flights", lambda: search(...))
+
+        # Govern an LLM call: reserve token budget before, reconcile actual usage after.
+        answer = trace.track_llm_call(
+            "summarize",
+            lambda: LlmCallResult(value=call_model(...), tokens=900, model="gpt"),
+            estimated_tokens=1000,
+        )
+
+        # Imperative authorization for a sensitive action (raises if denied).
+        # Send the spend's currency too — the platform converts it into the policy/budget
+        # currency before enforcing limits, so a USD charge is checked against a EUR cap.
+        client.ensure_authorized("payments:refund", {"amount": 280, "currency": "USD"})
+        trace.track_action("refund", lambda: do_refund(...), cost=Money.eur(280))
+# leaving the trace flushes its completion; leaving the client flushes remaining events.
+```
+
+Outbound HTTP can be auto-recorded as `tool_call` events by routing it through a tracked client:
+
+```python
+from tracengent import tracked_client
+
+http = tracked_client(client, base_url="https://api.example.com")
+http.get("/things")   # recorded as a tool_call, attached to the active trace
+```
+
+Declarative gating for web-hosted agents (the equivalent of .NET's `[RequireAgentPermission]`):
+
+```python
+from fastapi import FastAPI, Depends
+from tracengent.integrations.fastapi import install_tracengent, require_agent_permission
+
+app = FastAPI()
+install_tracengent(app, client)
+
+@app.post("/refunds", dependencies=[Depends(require_agent_permission("payments:refund"))])
+def refund(): ...        # 403s automatically when the agent lacks the permission
+```
+
+A Flask decorator (`tracengent.integrations.flask`) and a token-local coarse check
+(`client.has_permission("flights:book")`, no round-trip) are also available.
+
+**Tool governance (Phase 8).** Govern outbound tool calls the org doesn't own — block, hold for
+approval, or redact before the request leaves:
+
+```python
+from tracengent import governed_client
+
+# Every request through this client is authorized via /v1/tool-authorize first.
+tools = governed_client(client, base_url="https://api.stripe.com")
+tools.post("/v1/refunds", json={"amount": 280, "card": "4242"})
+# -> denied/held → raises; allowed → forwarded with any redactions applied.
+
+# Non-HTTP tools (MCP tools/call, LLM function calls):
+client.tools.guard_function("transfer_funds", {"to": "...", "amount": 50}, invoke=do_transfer)
+```
+
+**Delegation / agent-to-agent (Phase 5).** Act under a delegated token and attenuate authority for a
+downstream agent:
+
+```python
+session = client.begin_delegated_task(delegated_token)   # token granted out of band
+session.authorize("flights:book", {"amount": 280})       # intersects base policy with the grant
+
+# Mint a narrower child token to hand to another agent for an A2A hop:
+child = session.attenuate_for_call("agt_hotel", ["hotels:book"], max_amount=500)
+```
+
+Pure helpers are also exported directly:
+
+```python
+from tracengent import permission_matches, Redaction, apply_redactions
+
+permission_matches("flights:*", "flights:book")   # True
+apply_redactions('{"amount":100,"card":"4242"}', [Redaction("$.card", "mask")])
+# -> '{"amount":100,"card":"***REDACTED***"}'
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx` (HTTP transport)
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest -q          # unit tests
+ruff check .       # lint
+mypy               # type-check
+```
+
+CI runs lint + type-check + tests on every push (see [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml), job `sdk-python`).
+
+## Environment variables
+
+| Var | Meaning |
+|---|---|
+| `TRACENGENT_URL` | Base URL of the Tracengent API |
+| `TRACENGENT_CLIENT_ID` | Agent OAuth client id (`key_...`) — preferred |
+| `TRACENGENT_CLIENT_SECRET` | Agent OAuth client secret (`ags_...`) |
+| `TRACENGENT_INGEST_KEY` | Legacy org ingest key (`agk_...`) — fallback |
+| `TRACENGENT_AGENT_ID` | Logical agent key reported with events |
+| `TRACENGENT_ENVIRONMENT` | Environment tag (default `production`) |

tracengent-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tracengent"
+version = "0.1.0"
+description = "First-party Python SDK for Tracengent: instrument and govern agents (events, decision traces, authorization, tool governance, delegation)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Besar Kutleshi" }]
+keywords = ["agent", "observability", "governance", "authorization", "llm", "tracengent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "typing-extensions>=4.7; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+flask = ["flask>=3.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "fastapi>=0.110",
+    "flask>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/besarkutleshi/agentgov"
+Source = "https://github.com/besarkutleshi/agentgov"
+Repository = "https://github.com/besarkutleshi/agentgov.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracengent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+markers = [
+    "integration: end-to-end tests against a live platform (require TRACENGENT_TEST_* env vars)",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/tracengent"]

tracengent-0.1.0/samples/demo_agent.py

@@ -0,0 +1,66 @@
+"""A tiny end-to-end sample agent.
+
+Run against a live Tracengent platform with credentials in the environment::
+
+    export TRACENGENT_URL=http://localhost:8080
+    export TRACENGENT_CLIENT_ID=key_...
+    export TRACENGENT_CLIENT_SECRET=ags_...
+    python samples/demo_agent.py
+
+It opens a decision trace, records tool/LLM/action steps, authorizes a sensitive action, and
+governs an external tool call — exercising the same surface the .NET demo agent does.
+"""
+
+from __future__ import annotations
+
+import os
+
+from tracengent import (
+    LlmCallResult,
+    Money,
+    NotAuthorizedException,
+    TracengentClient,
+    TracengentOptions,
+    governed_client,
+)
+
+
+def main() -> None:
+    opts = TracengentOptions.from_env(agent_id=os.getenv("TRACENGENT_AGENT_ID", "demo-agent"))
+
+    with TracengentClient(opts) as client:
+        with client.begin_trace("book a trip to Lisbon", actor_user_id="u_demo") as trace:
+            trace.step("decided to search for flights")
+
+            flights = trace.track_tool_call(
+                "search-flights", lambda: [{"id": "LIS-JFK", "price": 280}]
+            )
+            print(f"found {len(flights)} flight(s)")
+
+            summary = trace.track_llm_call(
+                "summarize-options",
+                lambda: LlmCallResult(value="One direct flight for €280.", tokens=120, model="gpt"),
+                estimated_tokens=200,
+            )
+            print(f"summary: {summary}")
+
+            try:
+                client.ensure_authorized("payments:refund", {"amount": 280})
+                trace.track_action("charge-card", lambda: None, cost=Money.eur(280))
+                print("charged €280")
+            except NotAuthorizedException as ex:
+                print(f"charge not authorized: {ex.reason}")
+
+        # Govern an external tool the org doesn't own (raises if denied/held).
+        try:
+            tools = governed_client(client, base_url="https://api.example.com")
+            tools.get("/availability")
+            tools.close()
+        except Exception as ex:  # noqa: BLE001 — demo: surface governance outcomes, don't crash
+            print(f"external tool call governed: {ex}")
+
+    print("done; events flushed")
+
+
+if __name__ == "__main__":
+    main()

tracengent-0.1.0/src/tracengent/__init__.py

@@ -0,0 +1,81 @@
+"""Tracengent — first-party Python SDK for agent observability & governance.
+
+Through M3: configuration, the event model, OAuth token management, the background batching
+dispatcher (``record``), decision traces, auto-tracking, and authorization (``authorize`` /
+``ensure_authorized``). Tool governance and delegation arrive in later milestones.
+"""
+
+from __future__ import annotations
+
+from ._permissions import permission_matches
+from .authorization import AuthDecision, AuthObligations, NotAuthorizedException
+from .client import TracengentClient, new_id
+from .delegation import DelegatedSession, DelegationException
+from .events import (
+    Actor,
+    AgentEvent,
+    EventStatuses,
+    EventTypes,
+    LlmCallResult,
+    Money,
+    Usage,
+)
+from .options import TracengentConfigError, TracengentOptions
+from .redaction import MASK_TOKEN, Redaction
+from .redaction import apply as apply_redactions
+from .gateway import GatewayTransport, governed_client
+from .token_provider import AgentTokenProvider
+from .tool_gate import ToolGate, ToolGuardResult
+from .tool_governance import (
+    ToolDecision,
+    ToolDeniedException,
+    ToolPendingApprovalException,
+)
+from .trace import AgentTrace
+from .trace_context import current_trace
+from .tracking import TrackingTransport, tracked_client
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # config
+    "TracengentOptions",
+    "TracengentConfigError",
+    # client + telemetry
+    "TracengentClient",
+    "AgentEvent",
+    "Money",
+    "Usage",
+    "Actor",
+    "LlmCallResult",
+    "EventTypes",
+    "EventStatuses",
+    "AgentTokenProvider",
+    "new_id",
+    # traces
+    "AgentTrace",
+    "current_trace",
+    "TrackingTransport",
+    "tracked_client",
+    # authorization
+    "AuthDecision",
+    "AuthObligations",
+    "NotAuthorizedException",
+    # tool governance (Phase 8)
+    "ToolDecision",
+    "ToolDeniedException",
+    "ToolPendingApprovalException",
+    "ToolGate",
+    "ToolGuardResult",
+    "GatewayTransport",
+    "governed_client",
+    # delegation (Phase 5)
+    "DelegatedSession",
+    "DelegationException",
+    # helpers
+    "Redaction",
+    "apply_redactions",
+    "MASK_TOKEN",
+    "permission_matches",
+    "__version__",
+]

tracengent-0.1.0/src/tracengent/_auth.py

@@ -0,0 +1,41 @@
+"""Attaches auth to platform requests — mirrors the .NET ``AgentAuthHandler``.
+
+A per-agent bearer token (client-credentials) when configured, otherwise the legacy org ingest key
+header. On a 401 it refreshes the token once and retries. Returns ``None`` when the agent is disabled
+so the caller can count a drop instead of spamming the server.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from .options import TracengentOptions
+from .token_provider import AgentTokenProvider
+
+
+class AgentAuth:
+    def __init__(self, options: TracengentOptions, tokens: AgentTokenProvider) -> None:
+        self._o = options
+        self._tokens = tokens
+
+    def send(self, http: httpx.Client, request: httpx.Request) -> httpx.Response | None:
+        """Send ``request`` with auth applied. ``None`` means the agent is disabled (treat as a drop)."""
+        if self._o.uses_client_credentials:
+            token = self._tokens.get_token()
+            if token is None:
+                return None  # disabled — short-circuit locally
+            request.headers["Authorization"] = f"Bearer {token}"
+            response = http.send(request)
+            if response.status_code == httpx.codes.UNAUTHORIZED:
+                self._tokens.invalidate()
+                retry = self._tokens.get_token()
+                if retry is not None:
+                    response.close()
+                    request.headers["Authorization"] = f"Bearer {retry}"
+                    return http.send(request)
+            return response
+
+        # Legacy: org ingest key.
+        if self._o.ingest_key:
+            request.headers["X-Ingest-Key"] = self._o.ingest_key
+        return http.send(request)

tracengent-0.1.0/src/tracengent/_jwt.py

@@ -0,0 +1,62 @@
+"""Decode claims from a JWT *payload* (base64url) without a JWT library or signature validation.
+
+Mirrors the .NET ``JwtPayload`` helper and ``AgentTokenProvider.DecodePermissions``. This is used
+only for coarse, local hints (e.g. ``has_permission``) and to read delegation claims — it never
+validates the signature, so it must not be trusted for security decisions on its own.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from typing import Any
+
+
+def _decode_payload(jwt: str | None) -> dict[str, Any] | None:
+    """Base64url-decode the payload (second) segment of a JWT and parse it as a JSON object."""
+    if not jwt:
+        return None
+    parts = jwt.split(".")
+    if len(parts) < 2:
+        return None
+    try:
+        segment = parts[1]
+        # Restore base64url -> base64 and pad to a multiple of 4 (Python is strict about padding).
+        padded = segment + "=" * (-len(segment) % 4)
+        raw = base64.urlsafe_b64decode(padded)
+        obj = json.loads(raw)
+    except (binascii.Error, ValueError, UnicodeDecodeError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+def _as_str_list(value: Any) -> list[str]:
+    """Coerce a claim that may be an array of strings or a single string into a list[str]."""
+    if isinstance(value, list):
+        return [s for s in value if isinstance(s, str) and s]
+    if isinstance(value, str) and value:
+        return [value]
+    return []
+
+
+def read_string(jwt: str | None, claim: str) -> str | None:
+    """Read a string claim from the payload; ``None`` if absent or not a string."""
+    payload = _decode_payload(jwt)
+    if payload is None:
+        return None
+    value = payload.get(claim)
+    return value if isinstance(value, str) else None
+
+
+def read_string_array(jwt: str | None, claim: str) -> list[str]:
+    """Read a claim as a list of strings (accepts a single string or an array); empty if absent."""
+    payload = _decode_payload(jwt)
+    if payload is None:
+        return []
+    return _as_str_list(payload.get(claim))
+
+
+def decode_permissions(jwt: str | None) -> list[str]:
+    """Decode the ``permissions`` claim (array or single string) for coarse local checks."""
+    return read_string_array(jwt, "permissions")