agenthawk 0.2.0__py3-none-any.whl

agenthawk/__init__.py

@@ -0,0 +1,7 @@
+"""AgentHawk public import surface.
+
+The implementation remains in ``mcp_trace`` so existing integrations keep
+working. New code may import the query functions from ``agenthawk``.
+"""
+from mcp_trace import *  # noqa: F401,F403
+from mcp_trace import __version__

agenthawk/__main__.py

@@ -0,0 +1,4 @@
+from agenthawk.server import main
+
+if __name__ == "__main__":
+    main()

agenthawk/core.py

@@ -0,0 +1,2 @@
+"""AgentHawk query functions; compatibility implementation in ``mcp_trace.core``."""
+from mcp_trace.core import *  # noqa: F401,F403

agenthawk/server.py

@@ -0,0 +1,6 @@
+"""AgentHawk MCP server entry point."""
+from mcp_trace.server import *  # noqa: F401,F403
+from mcp_trace.server import main
+
+if __name__ == "__main__":
+    main()

agenthawk-0.2.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: agenthawk
+Version: 0.2.0
+Summary: Agent observability MCP server for querying OpenTelemetry traces, failures, tool health, security evidence, and regressions.
+Project-URL: Homepage, https://github.com/abhishekash/agenthawk
+Project-URL: Repository, https://github.com/abhishekash/agenthawk
+Project-URL: Issues, https://github.com/abhishekash/agenthawk/issues
+Author-email: Abhishek Ash <ash.abhishek@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent-evals,ai-agents,mcp,model-context-protocol,observability,opentelemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentHawk
+
+<!-- mcp-name: io.github.abhishekash/agenthawk -->
+
+[![CI](https://github.com/abhishekash/agenthawk/actions/workflows/ci.yml/badge.svg)](https://github.com/abhishekash/agenthawk/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Agents that can debug themselves.** An MCP server that exposes your agent runs — stored as plain OpenTelemetry JSONL span files — as queryable tools: runs, span trees, failures, tool health, security evidence, live activity, regressions, human-approval logs, token/cost usage.
+
+The idea: observability shouldn't be a dashboard you read after the fact. It should be *tools your agent can call mid-run* — "why was I slow yesterday?", "what did the human deny me last time?", "which tool keeps timing out?" — or query interactively from Claude Desktop / pi / any MCP client.
+
+Pairs with [agent-harness](https://github.com/abhishekash/agent-harness) (which writes the traces), but the reader is format-simple: any JSONL of OTel-shaped spans works.
+
+## AI-native use cases
+
+| Question during an agent run | MCP tool | Evidence returned |
+|---|---|---|
+| "Why did yesterday's run stall?" | `list_runs` → `slowest_spans` | Run IDs and the longest model or tool spans. |
+| "Did the agent act after I denied the write?" | `approval_log` → `span_tree` | The recorded decision and subsequent execution path. |
+| "How many model tokens did this run use?" | `token_usage` → `span_tree` | Run-level usage totals and the span tree for context. |
+| "Which tool is failing or timing out?" | `failure_report` / `tool_stats` | Redacted diagnostics, error rates, denials, and p95 latency. |
+| "Who/what was allowed to act?" | `security_audit` | Caller, tenant, server provenance, risk, and missing-evidence findings. |
+| "What is happening in the run right now?" | `recent_activity` | Cursor-based polling of newly written spans. |
+| "Did this model/version regress?" | `compare_runs` | Cost, latency, tokens, tool calls, and failure deltas. |
+
+The tools read stored traces and can poll files being written, but they do not push events or infer intent from the final answer. See the [real trace fixture](examples/example_trace.jsonl) and the [tool descriptions](src/mcp_trace/server.py) for the exact query contract.
+
+## Install & run
+
+AgentHawk is the new canonical name. The legacy `abhishekash-mcp-trace` distribution and `mcp-trace` commands remain compatibility aliases for existing users.
+
+```bash
+uvx agenthawk --trace-dir ./traces
+# or, for local development:
+git clone https://github.com/abhishekash/agenthawk
+cd agenthawk && uv pip install -e .
+agenthawk --trace-dir ./traces
+```
+
+The `agenthawk` 0.2.0 release is the renamed successor to the published
+[`abhishekash-mcp-trace` 0.1.1](https://pypi.org/project/abhishekash-mcp-trace/0.1.1/)
+distribution. Existing clients can continue using the legacy command while
+migrating.
+
+## Client configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["agenthawk", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**pi** (`~/.pi/agent/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["agenthawk", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**agent-harness** (mounted as gated tools):
+
+```bash
+harness run "Why was my last run slow?" --mcp "uvx agenthawk --trace-dir ./traces"
+```
+
+## Tools
+
+| Tool | Use it when |
+|---|---|
+| `list_runs` | Starting out — recent runs with task, model, duration, cost, decision counts |
+| `run_summary` | One run at a glance (accepts trace-id prefix) |
+| `span_tree` | "What did the agent actually do?" — nested shape of the run |
+| `slowest_spans` | "Why was it slow?" — top-k spans by duration |
+| `approval_log` | HITL audit — every approve/deny/**edit**, who decided, and *the rationale* |
+| `token_usage` | Cost questions — aggregated across runs or per-run |
+| `search_spans` | Find spans by tool name, file path, "denied", … |
+| `failure_report` | Find actionable, bounded, redacted errors and failed tool calls. |
+| `tool_stats` | Rank tools by volume, error rate, denials, and latency. |
+| `security_audit` | Audit caller identity, tenant, server provenance, risk, and approval evidence. |
+| `recent_activity` | Poll new spans with a cursor while a run is active. |
+| `compare_runs` | Compare selected traces for regressions across models or versions. |
+
+Tool descriptions are written as prompts (when-to-use, not just what-it-does) — descriptions are the interface for agent-called tools.
+
+## Example session (real fixture trace)
+
+```
+> list_runs
+[{ "trace_id": "f920798dd255…", "task": "Summarize the workspace's notes…",
+   "tool_calls": 4, "human_decisions": 2, "stopped_reason": "completed" }]
+
+> approval_log
+[{ "tool": "write_file", "decision": "approve", "approver": "auto", … },
+ { "tool": "run_shell",  "decision": "approve", "approver": "auto", … }]
+```
+
+## Design
+
+```
+traces/*.jsonl ──▶ agenthawk.core (pure query functions, zero deps)
+                          │
+                   agenthawk.server (thin MCPServer adapter, mcp 2.x)
+                          │
+                    stdio (NDJSON JSON-RPC)
+```
+
+- **core/server split**: all logic is pure functions over parsed spans; the MCP layer only parses args and JSON-encodes results. Tests hit both layers.
+- **trace_id prefixes**: agents fumble full 32-char hex ids; every tool accepts prefixes.
+- **bounded output**: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
+- **cursor polling**: `recent_activity` makes the snapshot reader useful while a run is still writing spans.
+- The demo fixture ([`examples/example_trace.jsonl`](examples/example_trace.jsonl)) is a *real* agent-harness run, not hand-written.
+
+## Research-driven gaps addressed
+
+A small Reddit review surfaced the same production problems repeatedly: auth and
+identity are unclear after the demo, versions and logs are hard to compare,
+tool fleets become noisy and expensive, operators lack visibility into what is
+happening, and raw logs are not a useful analysis surface. Examples:
+
+- [ChatGPT + MCP gets painful after the demo](https://www.reddit.com/r/ChatGPTPro/comments/1uz6tzs/where_chatgpt_mcp_gets_painful_after_the_demo/) — auth, versions, logs, and safe tools.
+- [MCP logging and correlation IDs](https://www.reddit.com/r/softwarearchitecture/comments/1r2wnfd/is_mcp_effectively_introducing_a_probabilistic/o51k4zq/) — preserve intent, tool arguments, results, and correlation IDs.
+- [180 tools becomes a permission/context/debugging problem](https://www.reddit.com/r/ClaudeAI/comments/1tuqqpn/i_ship_ai_agents_in_production_the_mess_is_mcp/opbh78y/).
+- [MCP security](https://www.reddit.com/r/cybersecurity/comments/1tgs4gg/mcp_security/) — identity, access, credentials, approved versions, and audit logs.
+- [Raw logs are noisy and hard to query](https://www.reddit.com/r/ChatGPTPro/comments/1ur2tx4/i_made_my_codex_usage_tracker_more_agentnative/).
+
+This update adds five focused query surfaces rather than pretending a
+Dashboard solves those problems: `failure_report`, `tool_stats`,
+`security_audit`, `recent_activity`, and `compare_runs`. Trace discovery is also
+recursive, and query results redact obvious credential patterns.
+
+## Honest limitations
+
+- stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
+- live polling re-reads snapshots; it is not a push subscription
+- security audit can only report identity/provenance that the trace producer records
+- read-only tools; trace mutation (annotations) is roadmap
+- `mcp_trace` remains the compatibility Python import; new code should use `agenthawk`
+
+## License
+
+MIT

agenthawk-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+agenthawk/__init__.py,sha256=3zuwO87lVDgfKmznSCcCyDzrSuMycHVj3OW4BVOqlE4,261
+agenthawk/__main__.py,sha256=DhRm9z974nLZZYQG9B1RwYVMqr7wT6TsxXhAbrPXU5Q,73
+agenthawk/core.py,sha256=fPtXteNMQY2vNWJwjd0Ac04B4BoQGZo2tgtKdkBeEuE,133
+agenthawk/server.py,sha256=XynTk8ycKh8_1aS1MGUuv24zkAcjhIm78H_MezDoKmg,163
+mcp_trace/__init__.py,sha256=mKoS0m7R7uw5sdLgVVuS_krrNdsLqONvWhJuGNpDvFg,784
+mcp_trace/__main__.py,sha256=_a1ue5xhiF_NlxafbnRzOQufSpjxCeN5kxAhHwv1618,95
+mcp_trace/core.py,sha256=Lv2GBz0xy6qKaXIQAPedAVMBguZpJ5d3asGPVgpCVg0,19999
+mcp_trace/server.py,sha256=1mMhmzccF-fYZG85Rgx1hbGAgoJcOj66h6GChBQo9Xs,5790
+agenthawk-0.2.0.dist-info/METADATA,sha256=p4sA4vXtwsYMfQI6t4Gh5CKHrzTywEmoXnsG1ANpbRI,8821
+agenthawk-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agenthawk-0.2.0.dist-info/entry_points.txt,sha256=Qu_9IU3aIs7hYfEYtW3qXAp5Jf7tkfqhTQFxQHO5lAQ,167
+agenthawk-0.2.0.dist-info/licenses/LICENSE,sha256=SJsmUc1lDzPkFMOSg3R0DTJdt983IP3kY_ow_TrzJ_E,1069
+agenthawk-0.2.0.dist-info/RECORD,,

agenthawk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agenthawk-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+abhishekash-mcp-trace = mcp_trace.server:main
+agent-hawk = mcp_trace.server:main
+agenthawk = mcp_trace.server:main
+mcp-trace = mcp_trace.server:main

agenthawk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Ash
+
+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.

mcp_trace/__init__.py

@@ -0,0 +1,41 @@
+"""AgentHawk: MCP server over trace query core.
+
+The ``mcp_trace`` import remains as a compatibility module for pre-0.2 users.
+"""
+from mcp_trace.core import (
+    approval_log,
+    compare_runs,
+    failure_report,
+    group_traces,
+    list_runs,
+    load_spans,
+    load_trace_dir,
+    recent_activity,
+    run_summary,
+    search_spans,
+    security_audit,
+    slowest_spans,
+    span_tree,
+    token_usage,
+    tool_stats,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "approval_log",
+    "compare_runs",
+    "failure_report",
+    "group_traces",
+    "list_runs",
+    "load_spans",
+    "load_trace_dir",
+    "recent_activity",
+    "run_summary",
+    "search_spans",
+    "security_audit",
+    "slowest_spans",
+    "span_tree",
+    "token_usage",
+    "tool_stats",
+    "__version__",
+]

mcp_trace/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from mcp_trace.server import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_trace/core.py

@@ -0,0 +1,523 @@
+"""Trace query engine over JSONL span files.
+
+Pure functions — no MCP or OTel imports — so the query logic is testable
+offline and reusable. The MCP server (server.py) is a thin adapter over this.
+
+Span format is the agent-harness contract: one JSON object per line with
+trace_id, span_id, parent_span_id, name, start/end unix nanos, status,
+attributes, events.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+# ---------------------------------------------------------------------------
+# loading
+
+
+def load_spans(path: str | Path) -> list[dict[str, Any]]:
+    spans: list[dict[str, Any]] = []
+    with Path(path).open(encoding="utf-8") as f:
+        for lineno, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                span = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"{path}:{lineno}: invalid span JSON: {e}") from e
+            span["_source_file"] = str(path)
+            spans.append(span)
+    return spans
+
+
+def load_trace_dir(trace_dir: str | Path) -> list[dict[str, Any]]:
+    """Load every JSONL span file below a trace directory."""
+    root = Path(trace_dir)
+    if not root.is_dir():
+        raise FileNotFoundError(f"trace dir not found: {root}")
+    spans: list[dict[str, Any]] = []
+    for path in sorted(p for p in root.rglob("*.jsonl") if p.is_file()):
+        spans.extend(load_spans(path))
+    return spans
+
+
+def group_traces(spans: Iterable[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+    traces: dict[str, list[dict[str, Any]]] = {}
+    for s in spans:
+        traces.setdefault(s["trace_id"], []).append(s)
+    for tid in traces:
+        traces[tid].sort(key=lambda s: (s["start_unix_nano"], s["end_unix_nano"]))
+    return traces
+
+
+# ---------------------------------------------------------------------------
+# queries
+
+
+_SECRET_PATTERNS = (
+    (r"(?i)(authorization\s*:\s*bearer\s+)[^\s,]+", r"\1<redacted>"),
+    (r"(?i)((?:api[_-]?key|token|secret|password)\s*[:=]\s*[\"']?)[^\s,\"']+", r"\1<redacted>"),
+    (r"(?i)\b(?:sk|ghp|github_pat|xoxb|xoxp)-[A-Za-z0-9_\-]{12,}\b", "<redacted>"),
+)
+
+
+def _redact_text(value: Any, limit: int = 500) -> str:
+    import re
+
+    text = str(value)
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = re.sub(pattern, replacement, text)
+    return text[:limit]
+
+
+def _status_code(span: dict[str, Any]) -> str:
+    status = span.get("status") or {}
+    code = status.get("code", "") if isinstance(status, dict) else ""
+    return str(code).upper()
+
+
+def _span_error(span: dict[str, Any]) -> bool:
+    attrs = span.get("attributes", {})
+    result_status = str(attrs.get("tool.result_status", "")).lower()
+    stopped = str(attrs.get("agent.stopped_reason", "")).lower()
+    events = span.get("events", []) or []
+    return bool(
+        _status_code(span) in {"ERROR", "2"}
+        or result_status in {"error", "denied"}
+        or attrs.get("tool.error")
+        or stopped not in {"", "completed"}
+        or any(str(event.get("name", "")).lower() in {"exception", "error"} for event in events)
+    )
+
+
+def _span_error_detail(span: dict[str, Any]) -> str | None:
+    attrs = span.get("attributes", {})
+    for key in (
+        "tool.error_message",
+        "error.message",
+        "exception.message",
+        "llm.error",
+        "agent.error",
+        "tool.error",
+        "agent.stopped_reason",
+    ):
+        if attrs.get(key) and not (
+            key == "agent.stopped_reason" and str(attrs[key]).lower() == "completed"
+        ):
+            return _redact_text(attrs[key])
+    for event in span.get("events", []) or []:
+        event_attrs = event.get("attributes", {}) or {}
+        for key in ("exception.message", "error.message"):
+            if event_attrs.get(key):
+                return _redact_text(event_attrs[key])
+    return None
+
+
+def _p95(values: list[float]) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    return ordered[min(len(ordered) - 1, round((len(ordered) - 1) * 0.95))]
+
+
+def _trace_groups(spans: Iterable[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+    return group_traces(spans)
+
+
+def _resolve_trace_prefix(spans: Iterable[dict[str, Any]], prefix: str) -> tuple[str, list[dict[str, Any]]]:
+    groups = _trace_groups(spans)
+    matches = [(trace_id, trace_spans) for trace_id, trace_spans in groups.items() if trace_id.startswith(prefix)]
+    if not matches:
+        raise ValueError(f"no trace matching {prefix!r}")
+    if len(matches) > 1:
+        raise ValueError(f"trace prefix {prefix!r} is ambiguous")
+    return matches[0]
+
+
+def _duration_ms(span: dict[str, Any]) -> float:
+    return max(0, span["end_unix_nano"] - span["start_unix_nano"]) / 1e6
+
+
+def _root(spans: list[dict[str, Any]]) -> dict[str, Any] | None:
+    ids = {s["span_id"] for s in spans}
+    for s in spans:
+        if s["parent_span_id"] is None or s["parent_span_id"] not in ids:
+            return s
+    return None
+
+
+def run_summary(trace_id: str, spans: list[dict[str, Any]]) -> dict[str, Any]:
+    """Compact summary of one run (one trace)."""
+    root = _root(spans)
+    attrs = (root or {}).get("attributes", {})
+    started = min(s["start_unix_nano"] for s in spans)
+    ended = max(s["end_unix_nano"] for s in spans)
+    llm_spans = [s for s in spans if s["name"] == "llm.complete"]
+    tool_spans = [s for s in spans if s["name"] == "tool.call"]
+    decisions = [
+        e for s in spans for e in s.get("events", []) if e["name"] == "hitl.decision"
+    ]
+    return {
+        "trace_id": trace_id,
+        "task": attrs.get("agent.task"),
+        "model": attrs.get("llm.model"),
+        "started_unix_nano": started,
+        "duration_ms": round((ended - started) / 1e6, 2),
+        "spans": len(spans),
+        "llm_calls": len(llm_spans),
+        "tool_calls": len(tool_spans),
+        "tools_used": sorted({s["attributes"].get("tool.name", "?") for s in tool_spans}),
+        "human_decisions": len(decisions),
+        "denials": sum(1 for e in decisions if e["attributes"].get("hitl.decision") == "deny"),
+        "input_tokens": attrs.get("agent.usage.input_tokens"),
+        "output_tokens": attrs.get("agent.usage.output_tokens"),
+        "cost_usd": attrs.get("agent.cost_usd"),
+        "stopped_reason": attrs.get("agent.stopped_reason"),
+        "source": (root or spans[0]).get("_source_file"),
+    }
+
+
+def list_runs(spans: list[dict[str, Any]], limit: int = 20) -> list[dict[str, Any]]:
+    """Newest-first summaries of every trace."""
+    traces = group_traces(spans)
+    summaries = [run_summary(tid, t) for tid, t in traces.items()]
+    summaries.sort(key=lambda s: s["started_unix_nano"], reverse=True)
+    return summaries[:limit]
+
+
+def span_tree(trace_id: str, spans: list[dict[str, Any]]) -> dict[str, Any]:
+    """Nested span tree with durations — the shape of the run."""
+    by_parent: dict[str | None, list[dict[str, Any]]] = {}
+    for s in spans:
+        by_parent.setdefault(s["parent_span_id"], []).append(s)
+    for children in by_parent.values():
+        children.sort(key=lambda s: s["start_unix_nano"])
+
+    def node(span: dict[str, Any]) -> dict[str, Any]:
+        events = [e["name"] for e in span.get("events", [])]
+        out = {
+            "name": span["name"],
+            "duration_ms": round(_duration_ms(span), 2),
+            "status": span["status"],
+            "events": events,
+            "children": [node(c) for c in by_parent.get(span["span_id"], [])],
+        }
+        attrs = span["attributes"]
+        keep = {
+            k: v
+            for k, v in attrs.items()
+            if k.startswith(("tool.", "llm.", "hitl.", "agent.stopped"))
+        }
+        if keep:
+            out["attributes"] = {
+                key: _redact_text(value) if isinstance(value, str) else value
+                for key, value in keep.items()
+            }
+        return out
+
+    root = _root(spans)
+    return node(root) if root else {"error": f"no root span in trace {trace_id}"}
+
+
+def slowest_spans(spans: list[dict[str, Any]], k: int = 5, name_filter: str | None = None) -> list[dict[str, Any]]:
+    """Top-k slowest spans — 'why was this run slow?' in one call."""
+    pool = [s for s in spans if name_filter is None or name_filter in s["name"]]
+    pool.sort(key=_duration_ms, reverse=True)
+    return [
+        {
+            "name": s["name"],
+            "duration_ms": round(_duration_ms(s), 2),
+            "tool": s["attributes"].get("tool.name"),
+            "trace_id": s["trace_id"],
+        }
+        for s in pool[:k]
+    ]
+
+
+def approval_log(spans: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Every human decision in a run: what was gated, who decided, why."""
+    out: list[dict[str, Any]] = []
+    for s in sorted(spans, key=lambda s: s["start_unix_nano"]):
+        tool = s["attributes"].get("tool.name", s["name"])
+        for e in s.get("events", []):
+            if e["name"] != "hitl.decision":
+                continue
+            a = e["attributes"]
+            out.append(
+                {
+                    "tool": tool,
+                    "decision": a.get("hitl.decision"),
+                    "approver": a.get("hitl.approver"),
+                    "rationale": _redact_text(a.get("hitl.rationale", "")),
+                    "edited": bool(a.get("hitl.edited")),
+                    "trace_id": s["trace_id"],
+                }
+            )
+    return out
+
+
+def token_usage(spans: list[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate token + cost accounting across llm.complete spans."""
+    in_tok = out_tok = 0
+    cost = 0.0
+    calls = 0
+    for s in spans:
+        if s["name"] != "llm.complete":
+            continue
+        calls += 1
+        in_tok += int(s["attributes"].get("llm.usage.input_tokens", 0))
+        out_tok += int(s["attributes"].get("llm.usage.output_tokens", 0))
+        cost += float(s["attributes"].get("llm.cost_usd", 0.0))
+    return {
+        "llm_calls": calls,
+        "input_tokens": in_tok,
+        "output_tokens": out_tok,
+        "total_tokens": in_tok + out_tok,
+        "cost_usd": round(cost, 8),
+    }
+
+
+def failure_report(
+    spans: list[dict[str, Any]],
+    *,
+    trace_id: str | None = None,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """Return actionable failed/error spans instead of raw JSONL.
+
+    This deliberately reports bounded, redacted diagnostics. It does not copy
+    normal tool output into the result, which keeps an observability query from
+    becoming a secret-exfiltration path.
+    """
+    pool = spans if trace_id is None else _resolve_trace_prefix(spans, trace_id)[1]
+    failures = [span for span in pool if _span_error(span)]
+    failures.sort(key=lambda span: span.get("start_unix_nano", 0), reverse=True)
+    out = []
+    for span in failures[: max(0, limit)]:
+        attrs = span.get("attributes", {})
+        out.append(
+            {
+                "trace_id": span.get("trace_id"),
+                "span_id": span.get("span_id"),
+                "name": span.get("name"),
+                "duration_ms": round(_duration_ms(span), 2),
+                "tool": attrs.get("tool.name"),
+                "status": _status_code(span) or "UNSET",
+                "result_status": attrs.get("tool.result_status"),
+                "detail": _span_error_detail(span),
+                "events": [event.get("name") for event in span.get("events", []) or []],
+            }
+        )
+    return out
+
+
+def tool_stats(
+    spans: list[dict[str, Any]],
+    *,
+    trace_id: str | None = None,
+    tool_name: str | None = None,
+    limit: int = 50,
+) -> list[dict[str, Any]]:
+    """Aggregate tool health: volume, latency, errors, and denials."""
+    pool = spans if trace_id is None else _resolve_trace_prefix(spans, trace_id)[1]
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for span in pool:
+        name = span.get("attributes", {}).get("tool.name")
+        if span.get("name") != "tool.call" or not name:
+            continue
+        if tool_name and name != tool_name:
+            continue
+        grouped.setdefault(str(name), []).append(span)
+
+    rows = []
+    for name, calls in grouped.items():
+        durations = [_duration_ms(span) for span in calls]
+        errors = [span for span in calls if _span_error(span)]
+        denials = [
+            event
+            for span in calls
+            for event in span.get("events", []) or []
+            if event.get("name") == "hitl.decision"
+            and event.get("attributes", {}).get("hitl.decision") == "deny"
+        ]
+        last_error = next((_span_error_detail(span) for span in calls if _span_error_detail(span)), None)
+        rows.append(
+            {
+                "tool": name,
+                "calls": len(calls),
+                "errors": len(errors),
+                "error_rate": round(len(errors) / len(calls), 4),
+                "denials": len(denials),
+                "mean_duration_ms": round(sum(durations) / len(durations), 2),
+                "p95_duration_ms": round(_p95(durations), 2),
+                "last_error": last_error,
+                "traces": sorted({span.get("trace_id") for span in calls}),
+            }
+        )
+    rows.sort(key=lambda row: (-row["errors"], -row["mean_duration_ms"], row["tool"]))
+    return rows[: max(0, limit)]
+
+
+def security_audit(
+    spans: list[dict[str, Any]],
+    *,
+    trace_id: str | None = None,
+    limit: int = 100,
+) -> dict[str, Any]:
+    """Summarize identity, provenance, authorization, and dangerous actions.
+
+    Missing identity/provenance is returned explicitly as a finding. The trace
+    reader cannot infer who authorized a call when the producer did not record
+    it.
+    """
+    pool = spans if trace_id is None else _resolve_trace_prefix(spans, trace_id)[1]
+    calls = [span for span in pool if span.get("name") == "tool.call"]
+    identity_keys = ("agent.identity", "auth.subject", "user.id", "mcp.client_id")
+    tenant_keys = ("auth.tenant", "tenant.id", "agent.tenant")
+    server_keys = ("mcp.server", "mcp.server.name", "mcp.server.version")
+    records = []
+    missing_identity = 0
+    missing_provenance = 0
+    denied = 0
+    for index, span in enumerate(sorted(calls, key=lambda item: item.get("start_unix_nano", 0))):
+        attrs = span.get("attributes", {})
+        identity = next((attrs[key] for key in identity_keys if attrs.get(key)), None)
+        tenant = next((attrs[key] for key in tenant_keys if attrs.get(key)), None)
+        server = next((attrs[key] for key in server_keys if attrs.get(key)), None)
+        decision_events = [
+            event for event in span.get("events", []) or [] if event.get("name") == "hitl.decision"
+        ]
+        decision = decision_events[-1].get("attributes", {}).get("hitl.decision") if decision_events else None
+        if not identity:
+            missing_identity += 1
+        if not server:
+            missing_provenance += 1
+        if decision == "deny":
+            denied += 1
+        if index >= max(0, limit):
+            continue
+        records.append(
+            {
+                "trace_id": span.get("trace_id"),
+                "span_id": span.get("span_id"),
+                "tool": attrs.get("tool.name"),
+                "risk": attrs.get("tool.risk"),
+                "identity": _redact_text(identity) if identity else None,
+                "tenant": _redact_text(tenant) if tenant else None,
+                "server": _redact_text(server) if server else None,
+                "decision": decision,
+                "result_status": attrs.get("tool.result_status"),
+            }
+        )
+    return {
+        "calls": len(calls),
+        "denied": denied,
+        "missing_identity": missing_identity,
+        "missing_server_provenance": missing_provenance,
+        "findings": [
+            finding
+            for finding in (
+                "tool calls lack recorded caller identity" if missing_identity else None,
+                "tool calls lack recorded MCP server provenance" if missing_provenance else None,
+            )
+            if finding
+        ],
+        "records": records,
+    }
+
+
+def recent_activity(
+    spans: list[dict[str, Any]],
+    *,
+    cursor: str | None = None,
+    trace_id: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """Return an incremental, redacted span feed for polling a live directory."""
+    pool = spans if trace_id is None else _resolve_trace_prefix(spans, trace_id)[1]
+    after = (0, "")
+    if cursor:
+        try:
+            start, span_id = cursor.split(":", 1)
+            after = (int(start), span_id)
+        except ValueError as exc:
+            raise ValueError("cursor must be '<start_unix_nano>:<span_id>'") from exc
+    ordered = sorted(
+        (span for span in pool if (span.get("start_unix_nano", 0), span.get("span_id", "")) > after),
+        key=lambda span: (span.get("start_unix_nano", 0), span.get("span_id", "")),
+    )
+    selected = ordered[: max(0, limit)]
+    records = []
+    for span in selected:
+        attrs = span.get("attributes", {})
+        records.append(
+            {
+                "trace_id": span.get("trace_id"),
+                "span_id": span.get("span_id"),
+                "name": span.get("name"),
+                "start_unix_nano": span.get("start_unix_nano"),
+                "duration_ms": round(_duration_ms(span), 2),
+                "status": _status_code(span) or "UNSET",
+                "tool": attrs.get("tool.name"),
+                "result_status": attrs.get("tool.result_status"),
+                "error": _span_error_detail(span),
+                "events": [event.get("name") for event in span.get("events", []) or []],
+            }
+        )
+    next_cursor = cursor
+    if selected:
+        last = selected[-1]
+        next_cursor = f"{last.get('start_unix_nano', 0)}:{last.get('span_id', '')}"
+    return {"next_cursor": next_cursor, "count": len(records), "spans": records}
+
+
+def compare_runs(spans: list[dict[str, Any]], trace_ids: list[str]) -> dict[str, Any]:
+    """Compare selected runs for latency, cost, tokens, tools, and failures."""
+    if not trace_ids:
+        raise ValueError("trace_ids must contain at least one trace-id prefix")
+    runs = []
+    for prefix in trace_ids:
+        full_id, trace_spans = _resolve_trace_prefix(spans, prefix)
+        summary = run_summary(full_id, trace_spans)
+        usage = token_usage(trace_spans)
+        runs.append(
+            {
+                "trace_id": full_id,
+                "task": summary.get("task"),
+                "model": summary.get("model"),
+                "stopped_reason": summary.get("stopped_reason"),
+                "duration_ms": summary.get("duration_ms", 0),
+                "cost_usd": usage["cost_usd"],
+                "total_tokens": usage["total_tokens"],
+                "tool_calls": summary.get("tool_calls", 0),
+                "failures": len(failure_report(trace_spans)),
+            }
+        )
+    baseline = runs[0]
+    numeric = ("duration_ms", "cost_usd", "total_tokens", "tool_calls", "failures")
+    for run in runs:
+        run["delta_vs_first"] = {
+            key: round(float(run[key]) - float(baseline[key]), 8) for key in numeric
+        }
+    return {"baseline": baseline["trace_id"], "runs": runs}
+
+
+def search_spans(spans: list[dict[str, Any]], needle: str) -> list[dict[str, Any]]:
+    """Substring search over span names and attribute values."""
+    needle_l = needle.lower()
+    hits = []
+    for s in spans:
+        haystacks = [s["name"]] + [str(v) for v in s["attributes"].values()]
+        if any(needle_l in h.lower() for h in haystacks):
+            hits.append(
+                {
+                    "trace_id": s["trace_id"],
+                    "name": s["name"],
+                    "duration_ms": round(_duration_ms(s), 2),
+                    "matched": [_redact_text(h) for h in haystacks if needle_l in h.lower()][:3],
+                }
+            )
+    return hits

mcp_trace/server.py

@@ -0,0 +1,163 @@
+"""FastMCP stdio server: agents querying their own traces.
+
+Tool design notes (these are prompts, not just schemas):
+- every tool says *when* to use it, not just what it does
+- results are compact JSON; trees are the only nested shape
+- trace_dir comes from --trace-dir / MCP_TRACE_DIR / ./traces
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+
+from mcp_trace import core
+
+mcp = MCPServer(
+    "agenthawk",
+    instructions=(
+        "Query OpenTelemetry traces of agent runs (JSONL span files). "
+        "Use list_runs to see recent runs, run_summary/span_tree to inspect one, "
+        "slowest_spans for latency questions, approval_log for what humans "
+        "approved/denied, token_usage for cost questions, failure_report for "
+        "errors, tool_stats for tool health, security_audit for identity and "
+        "provenance gaps, recent_activity for incremental live polling, and "
+        "compare_runs for regressions."
+    ),
+)
+
+_trace_dir: Path = Path("./traces")
+
+
+def _spans() -> list[dict]:
+    try:
+        return core.load_trace_dir(_trace_dir)
+    except FileNotFoundError:
+        return []
+
+
+def _resolve(trace_id: str) -> list[dict]:
+    spans = [s for s in _spans() if s["trace_id"].startswith(trace_id)]
+    if not spans:
+        known = ", ".join(t[:12] for t in core.group_traces(_spans())) or "(none)"
+        raise ValueError(f"no trace matching {trace_id!r}; known prefixes: {known}")
+    return spans
+
+
+def _dump(obj) -> str:
+    return json.dumps(obj, indent=2, ensure_ascii=False, default=str)
+
+
+@mcp.tool()
+def list_runs(limit: int = 10) -> str:
+    """List recent agent runs: task, model, duration, tool use, human decisions, cost.
+
+    Use first to find the trace_id for deeper inspection.
+    """
+    runs = core.list_runs(_spans(), limit=limit)
+    if not runs:
+        return f"No traces found in {_trace_dir}. Point --trace-dir at your harness traces."
+    for r in runs:
+        r["trace_id"] = r["trace_id"][:12] + "…"
+    return _dump(runs)
+
+
+@mcp.tool()
+def run_summary(trace_id: str) -> str:
+    """Compact summary of one run (accepts trace_id prefix)."""
+    spans = _resolve(trace_id)
+    return _dump(core.run_summary(spans[0]["trace_id"], spans))
+
+
+@mcp.tool()
+def span_tree(trace_id: str) -> str:
+    """Nested span tree of a run — the shape of what the agent did, with durations."""
+    spans = _resolve(trace_id)
+    return _dump(core.span_tree(spans[0]["trace_id"], spans))
+
+
+@mcp.tool()
+def slowest_spans(trace_id: str | None = None, k: int = 5) -> str:
+    """Top-k slowest spans. Use for 'why was this run slow?'. Omit trace_id to search all runs."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.slowest_spans(spans, k=k))
+
+
+@mcp.tool()
+def approval_log(trace_id: str | None = None) -> str:
+    """Human-in-the-loop audit: every approval/denial/edit, who decided, and the rationale.
+
+    Use when asked 'why did the agent get to do X?' or 'what was denied?'.
+    """
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.approval_log(spans))
+
+
+@mcp.tool()
+def token_usage(trace_id: str | None = None) -> str:
+    """Token and cost totals. Omit trace_id to aggregate across all runs."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.token_usage(spans))
+
+
+@mcp.tool()
+def search_spans(needle: str, trace_id: str | None = None) -> str:
+    """Substring search over span names/attributes, e.g. a tool name, file path, or 'denied'."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.search_spans(spans, needle))
+
+
+@mcp.tool()
+def failure_report(trace_id: str | None = None, limit: int = 20) -> str:
+    """Show bounded, redacted tool/provider failures and their actionable diagnostics."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.failure_report(spans, trace_id=None, limit=limit))
+
+
+@mcp.tool()
+def tool_stats(trace_id: str | None = None, tool_name: str | None = None, limit: int = 50) -> str:
+    """Rank tools by errors, denials, latency, and call volume to find unhealthy integrations."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.tool_stats(spans, trace_id=None, tool_name=tool_name, limit=limit))
+
+
+@mcp.tool()
+def security_audit(trace_id: str | None = None, limit: int = 100) -> str:
+    """Audit caller identity, tenant, server provenance, risk, and approval evidence for tool calls."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.security_audit(spans, trace_id=None, limit=limit))
+
+
+@mcp.tool()
+def recent_activity(
+    cursor: str | None = None,
+    trace_id: str | None = None,
+    limit: int = 50,
+) -> str:
+    """Poll newly written spans using a cursor; useful while an agent run is still active."""
+    spans = _resolve(trace_id) if trace_id else _spans()
+    return _dump(core.recent_activity(spans, cursor=cursor, trace_id=None, limit=limit))
+
+
+@mcp.tool()
+def compare_runs(trace_ids: list[str]) -> str:
+    """Compare selected trace-id prefixes for latency, cost, tokens, tools, and failures."""
+    return _dump(core.compare_runs(_spans(), trace_ids))
+
+
+def main() -> None:
+    global _trace_dir
+    parser = argparse.ArgumentParser(description="MCP server for agent self-observability")
+    parser.add_argument(
+        "--trace-dir",
+        default=os.environ.get("MCP_TRACE_DIR", "./traces"),
+        help="directory of JSONL span files (default: $MCP_TRACE_DIR or ./traces)",
+    )
+    args = parser.parse_args()
+    _trace_dir = Path(args.trace_dir).resolve()
+    print(f"AgentHawk serving traces from {_trace_dir}", file=sys.stderr)
+    mcp.run(transport="stdio")