agenthawk 0.2.0__tar.gz

agenthawk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

agenthawk-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,26 @@
+name: publish-pypi
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

agenthawk-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+traces/
+runs.jsonl
+.env

agenthawk-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to AgentHawk
+
+## Development setup
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+pytest -q
+```
+
+The core query engine is dependency-light and should remain pure. Server tests exercise the MCP 2.x protocol adapter as well as the core functions.
+
+## Pull requests
+
+- Add a deterministic fixture for new query behavior.
+- Test the tool through `MCPServer.call_tool`, not only by calling the underlying function.
+- Keep tool descriptions phrased as when-to-use prompts.
+- Preserve trace-id prefix support and compact output defaults.
+- Update the README's tool table and limitations when behavior changes.

agenthawk-0.2.0/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.

agenthawk-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,153 @@
+# 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/examples/example_trace.jsonl

@@ -0,0 +1,15 @@
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "047527cfe5a06b79", "parent_span_id": "b3870190725e6c0a", "name": "llm.complete", "start_unix_nano": 1791446657381364374, "end_unix_nano": 1791446657381395204, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 92, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "cf9ec887533385eb", "parent_span_id": "b3870190725e6c0a", "name": "tool.call", "start_unix_nano": 1791446657381557076, "end_unix_nano": 1791446657381753320, "status": "UNSET", "attributes": {"tool.name": "list_dir", "tool.risk": "read", "tool.call_id": "call_1d4b88534934", "tool.duration_ms": 0.17095799557864666}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "b3870190725e6c0a", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657381336939, "end_unix_nano": 1791446657381830109, "status": "UNSET", "attributes": {"step.index": 1}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "3a1883f304c6810a", "parent_span_id": "060258fcbbc7b4b2", "name": "llm.complete", "start_unix_nano": 1791446657381913540, "end_unix_nano": 1791446657381938066, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 94, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "ec96e325ccf2812b", "parent_span_id": "060258fcbbc7b4b2", "name": "tool.call", "start_unix_nano": 1791446657382001356, "end_unix_nano": 1791446657382097431, "status": "UNSET", "attributes": {"tool.name": "read_file", "tool.risk": "read", "tool.call_id": "call_e67e16d926b0", "tool.duration_ms": 0.08226605132222176}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "060258fcbbc7b4b2", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657381892888, "end_unix_nano": 1791446657382146922, "status": "UNSET", "attributes": {"step.index": 2}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "b07c48a63a82f767", "parent_span_id": "0bd568f46e01fc65", "name": "llm.complete", "start_unix_nano": 1791446657382220834, "end_unix_nano": 1791446657382241746, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 125, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "d6bc66fcba6ba958", "parent_span_id": "0bd568f46e01fc65", "name": "tool.call", "start_unix_nano": 1791446657382294447, "end_unix_nano": 1791446657382449645, "status": "UNSET", "attributes": {"tool.name": "write_file", "tool.risk": "write", "tool.call_id": "call_8a5a534020b7", "hitl.required": true, "tool.duration_ms": 0.11282693594694138}, "events": [{"name": "hitl.decision", "time_unix_nano": 1791446657382326440, "attributes": {"hitl.decision": "approve", "hitl.approver": "auto", "hitl.rationale": "auto-approved (unattended run)"}}]}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "0bd568f46e01fc65", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657382193796, "end_unix_nano": 1791446657382508737, "status": "UNSET", "attributes": {"step.index": 3}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "70d5591a02be91d6", "parent_span_id": "e83a45284010e5c7", "name": "llm.complete", "start_unix_nano": 1791446657382582514, "end_unix_nano": 1791446657382605733, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 132, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "0f176ff0f2ed3f5f", "parent_span_id": "e83a45284010e5c7", "name": "tool.call", "start_unix_nano": 1791446657382663037, "end_unix_nano": 1791446657384990883, "status": "UNSET", "attributes": {"tool.name": "run_shell", "tool.risk": "execute", "tool.call_id": "call_9a19cc1b4ead", "hitl.required": true, "tool.duration_ms": 2.2949520498514175}, "events": [{"name": "hitl.decision", "time_unix_nano": 1791446657382685591, "attributes": {"hitl.decision": "approve", "hitl.approver": "auto", "hitl.rationale": "auto-approved (unattended run)"}}]}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "e83a45284010e5c7", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657382563796, "end_unix_nano": 1791446657385069850, "status": "UNSET", "attributes": {"step.index": 4}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "7e5dff5291ab7ee6", "parent_span_id": "7523732e099104c7", "name": "llm.complete", "start_unix_nano": 1791446657385145680, "end_unix_nano": 1791446657385168372, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 196, "llm.usage.output_tokens": 14, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "7523732e099104c7", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657385127184, "end_unix_nano": 1791446657385204759, "status": "UNSET", "attributes": {"step.index": 5}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "aec12b5c51ce2580", "parent_span_id": null, "name": "agent.run", "start_unix_nano": 1791446657381269974, "end_unix_nano": 1791446657385251046, "status": "UNSET", "attributes": {"agent.task": "Summarize the workspace's notes into SUMMARY.md, then verify it with ls", "agent.max_steps": 12, "agent.tools": ["list_dir", "read_file", "run_shell", "write_file"], "agent.skills": [], "llm.model": "scripted", "agent.steps": 5, "agent.stopped_reason": "completed", "agent.usage.input_tokens": 639, "agent.usage.output_tokens": 50, "agent.cost_usd": 0.0, "agent.approvals": 2}, "events": []}

agenthawk-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenthawk"
+version = "0.2.0"
+description = "Agent observability MCP server for querying OpenTelemetry traces, failures, tool health, security evidence, and regressions."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Abhishek Ash", email = "ash.abhishek@gmail.com" }]
+keywords = ["mcp", "model-context-protocol", "ai-agents", "observability", "opentelemetry", "agent-evals"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+agenthawk = "mcp_trace.server:main"
+agent-hawk = "mcp_trace.server:main"
+mcp-trace = "mcp_trace.server:main"
+abhishekash-mcp-trace = "mcp_trace.server:main"
+
+[project.urls]
+Homepage = "https://github.com/abhishekash/agenthawk"
+Repository = "https://github.com/abhishekash/agenthawk"
+Issues = "https://github.com/abhishekash/agenthawk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_trace", "src/agenthawk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

agenthawk-0.2.0/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.abhishekash/agenthawk",
+  "title": "AgentHawk",
+  "description": "Query OpenTelemetry traces from agent runs through MCP.",
+  "repository": {
+    "url": "https://github.com/abhishekash/agenthawk",
+    "source": "github"
+  },
+  "version": "0.2.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "agenthawk",
+      "version": "0.2.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

agenthawk-0.2.0/src/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-0.2.0/src/agenthawk/__main__.py

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

agenthawk-0.2.0/src/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-0.2.0/src/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/src/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__",
+]

agenthawk-0.2.0/src/mcp_trace/__main__.py

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