agentdebugx 0.3.1__tar.gz → 0.4.0__tar.gz

{agentdebugx-0.3.1 → agentdebugx-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdebugx
-Version: 0.3.1
+Version: 0.4.0
 Summary: Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`.
 License: MIT
 License-File: LICENSE
@@ -28,36 +28,33 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: crewai
 Provides-Extra: gui
+Provides-Extra: gui-app
+Provides-Extra: gui-memory
 Provides-Extra: hub-hf
 Provides-Extra: langgraph
 Provides-Extra: openai-agents
 Provides-Extra: otel
 Provides-Extra: ui
-Requires-Dist: anthropic ; extra == "gui" or extra == "all"
-Requires-Dist: backoff ; extra == "gui" or extra == "all"
-Requires-Dist: chromadb ; extra == "gui" or extra == "all"
+Requires-Dist: anthropic ; extra == "gui-app" or extra == "all"
+Requires-Dist: chromadb ; extra == "gui-memory" or extra == "all"
 Requires-Dist: crewai ; extra == "crewai" or extra == "all"
 Requires-Dist: fastapi ; extra == "ui" or extra == "all"
 Requires-Dist: httpx (>=0.24,<1.0)
 Requires-Dist: huggingface_hub ; extra == "hub-hf" or extra == "all"
-Requires-Dist: langchain-chroma ; extra == "gui" or extra == "all"
-Requires-Dist: langchain-core ; extra == "langgraph" or extra == "gui" or extra == "all"
-Requires-Dist: langchain-openai ; extra == "gui" or extra == "all"
-Requires-Dist: matplotlib ; extra == "gui" or extra == "all"
-Requires-Dist: numpy ; extra == "gui" or extra == "all"
-Requires-Dist: openai ; extra == "gui" or extra == "all"
+Requires-Dist: langchain-chroma ; extra == "gui-memory" or extra == "all"
+Requires-Dist: langchain-core ; extra == "langgraph" or extra == "gui-memory" or extra == "all"
+Requires-Dist: langchain-openai ; extra == "gui-memory" or extra == "all"
+Requires-Dist: openai ; extra == "gui-app" or extra == "all"
 Requires-Dist: openai-agents ; extra == "openai-agents" or extra == "all"
 Requires-Dist: opentelemetry-api ; extra == "otel" or extra == "all"
 Requires-Dist: opentelemetry-sdk ; extra == "otel" or extra == "all"
-Requires-Dist: pandas ; extra == "gui" or extra == "all"
-Requires-Dist: pillow ; extra == "gui" or extra == "all"
+Requires-Dist: pandas ; extra == "gui-app" or extra == "all"
+Requires-Dist: pillow ; extra == "gui" or extra == "gui-app" or extra == "all"
 Requires-Dist: pydantic (>=1.10,<3.0)
-Requires-Dist: python-dotenv ; extra == "gui" or extra == "all"
-Requires-Dist: scikit-learn ; extra == "gui" or extra == "all"
-Requires-Dist: streamlit ; extra == "gui" or extra == "all"
-Requires-Dist: streamlit-adjustable-columns ; extra == "gui" or extra == "all"
-Requires-Dist: together ; extra == "gui" or extra == "all"
-Requires-Dist: tqdm ; extra == "gui" or extra == "all"
+Requires-Dist: scikit-learn ; extra == "gui-memory" or extra == "all"
+Requires-Dist: streamlit ; extra == "gui-app" or extra == "all"
+Requires-Dist: streamlit-adjustable-columns ; extra == "gui-app" or extra == "all"
+Requires-Dist: together ; extra == "gui-app" or extra == "all"
 Requires-Dist: uvicorn ; extra == "ui" or extra == "all"
 Project-URL: Documentation, https://github.com/AgentDebugX/AgentDebugX
 Project-URL: Homepage, https://www.agentdebugx.com
@@ -73,6 +70,7 @@ Description-Content-Type: text/markdown
 **A local-first debugging framework for agentic AI systems: diagnose failures, attribute root causes, recover with evidence, and validate fixes through reruns.**
 
 <a href="https://www.agentdebugx.com"><img src="https://img.shields.io/badge/WEBSITE-208B57?style=for-the-badge&logo=googlechrome&logoColor=white" alt="AgentDebugX website"></a>
+<a href="https://docs.agentdebugx.com/"><img src="https://img.shields.io/badge/DOCS-176B45?style=for-the-badge&logo=materialformkdocs&logoColor=white" alt="AgentDebugX documentation"></a>
 <a href="https://github.com/AgentDebugX/AgentDebugX"><img src="https://img.shields.io/badge/GITHUB-24292F?style=for-the-badge&logo=github&logoColor=white" alt="AgentDebugX GitHub repository"></a>
 <a href="https://youtu.be/ztni6w0o_l8"><img src="https://img.shields.io/badge/DEMO_VIDEO-EA4335?style=for-the-badge&logo=youtube&logoColor=white" alt="AgentDebugX demo video"></a>
 
@@ -99,6 +97,24 @@ runners, and local agent development workflows. AgentDebugX is local-first by
 default: traces stay on your machine, sharing is opt-in, and recovery proposals
 carry explicit policy and approval metadata into the Rerun boundary.
 
+## 📰 News
+
+- 🔌 **2026-08-25** — Released
+  [`dsh-agentdebugx` v0.1.0](https://www.npmjs.com/package/dsh-agentdebugx),
+  the AgentDebugX plugin for DeepSeek Harness.
+- 📄 **2026-07-31** — Released
+  [CUADebug](https://arxiv.org/abs/2608.02643), our framework for diagnosing
+  and repairing computer-use agent failures.
+- 📄 **2026-07-21** — Released the
+  [AgentDebugX paper](https://arxiv.org/abs/2607.18754), presenting our
+  open-source toolkit for failure observability, attribution, recovery, and
+  rerun in LLM agents.
+- 📦 **2026-05-16** — Released AgentDebugX on
+  [PyPI](https://pypi.org/project/agentdebugx/).
+- 📄 **2025-09-29** — Released
+  [Where LLM Agents Fail and How They Can Learn From Failures](https://arxiv.org/abs/2509.25370),
+  introducing AgentErrorTaxonomy, AgentErrorBench, and AgentDebug.
+
 ## System Overview
 
 <p align="center">
@@ -146,7 +162,8 @@ agentic skill.
 - **Rerun**: three explicit modes for plan/export only, labeled simulation, or
   observed execution in an application-owned process or persistent HTTP runner.
 - **Local inspection UI**: no-build FastAPI dashboard for traces, reports,
-  saved cases, debug branches, and rerun-from-event workflows.
+  before/after CUA visuals, debugger discussions, saved cases, debug branches,
+  and rerun-from-event workflows.
 - **Error Hub**: scrubbed, shareable failure bundles for regression tests,
   benchmark corpora, and team debugging memory.
 - **Agent integrations**: generate host-runtime assets such as debugging skills
@@ -166,16 +183,67 @@ pip install "agentdebugx[langgraph]"      # LangGraph adapter
 pip install "agentdebugx[crewai]"         # CrewAI adapter
 pip install "agentdebugx[openai-agents]"  # OpenAI Agents SDK adapter
 pip install "agentdebugx[otel]"           # OpenTelemetry ingest
-pip install "agentdebugx[gui]"            # computer-use / OSWorld GUI tooling
+pip install "agentdebugx[gui]"            # screenshot decoding for GUI RCA
 pip install "agentdebugx[all]"            # all optional integrations
 ```
 
+Computer-use / OSWorld GUI root-cause analysis (`agentdebug.gui`) ships with the
+core install and needs no extra. The `gui` extra only adds `pillow`, which the
+RCA tools use to decode screenshots. Two heavier layers of the same package sit
+behind their own extras: `gui-memory` for the lesson/episodic memory stack, and
+`gui-app` for the provider adapters, the batch pipeline (`python -m
+agentdebug.gui`) and the Streamlit annotation app.
+
 The package is installed as `agentdebugx` and imported as `agentdebug`:
 
 ```python
 import agentdebug
 ```
 
+## Claude Code and Codex Plugins
+
+AgentDebugX ships native plugins for Claude Code and Codex so an agent can
+debug its own session. The plugin bundles capture hooks and the AgentDebug
+skill, which keeps two boundaries explicit:
+
+- **Capture is automatic** once a project opts in. Sessions are normalized into
+  AgentDebugX trajectories locally and silently.
+- **Diagnosis is explicit.** Ask AgentDebug in-session and the skill diagnoses
+  that exact captured trajectory with `agentdebug run --current --profile deep`.
+  Re-running or repairing the agent's work stays a separately authorized step.
+
+Follow the [capture quickstart](CAPTURE_QUICKSTART.md) to install a plugin,
+enable project capture, diagnose a session, and turn capture off again.
+
+The plugin bundles live in this repository:
+
+| Plugin | Bundle | Documentation |
+| --- | --- | --- |
+| Claude Code | `integrations/claude-code/plugins/agentdebug` | [Claude Code plugin](integrations/claude-code/README.md) |
+| Codex | `integrations/codex/plugins/agentdebug` | [Codex plugin](integrations/codex/README.md) |
+
+Each plugin's documentation covers its hooks, install scope, the capture
+consent step, and lazy session creation. See
+[`src/agentdebug/capture/README.md`](src/agentdebug/capture/README.md) for the
+stored `.agentdebug/` layout and
+[`src/agentdebug/workbench/README.md`](src/agentdebug/workbench/README.md) for
+`agentdebug run` profiles and run manifests.
+
+## DeepSeek Harness Plugin
+
+AgentDebugX is also available as the
+[`dsh-agentdebugx`](https://www.npmjs.com/package/dsh-agentdebugx) plugin for
+DeepSeek Harness. It diagnoses current and saved Harness trajectories and
+starts the Python bridge and local dashboard only when they are needed.
+
+```bash
+pip install "agentdebugx[ui]>=0.3.1,<0.4"
+dsh plugin --profile web add dsh-agentdebugx
+```
+
+See the [plugin documentation](integrations/dsh-agentdebugx/README.md) for
+configuration, commands, saved-session discovery, and deep diagnosis.
+
 ## Quick Start: Python API
 
 Record a trajectory and analyze it locally:
@@ -228,7 +296,7 @@ agentdebug ingest raw_trace.json --format auto --out trace.json
 
 Use `--format` when the source is known, for example `messages`,
 `openai_agents_spans`, `crewai_events`, `langgraph_callbacks`, `claude_code`,
-or `osworld`.
+`codex`, or `osworld`.
 
 Process a directory of independent JSON files or every non-empty line in a
 JSONL dataset:
@@ -352,6 +420,19 @@ agentdebug rerun report.json \
   --out rerun.live.json
 ```
 
+To branch from a specific trajectory event, pass its 1-based event number:
+
+```bash
+agentdebug rerun report.json \
+  --trajectory trace.json \
+  --start-event 4 \
+  --out rerun.from-event.json
+```
+
+`--start-event N` resolves the Nth event to its stable event ID and sends a
+`from_event` checkpoint to plan, simulation, and live runner modes. The selected
+runner must support restoring or continuing from event checkpoints.
+
 The service owns the framework, real model, tools, credentials, environment,
 job lifecycle, and trajectory recorder. A chat-completions URL alone is not an
 Agent environment. Submissions are idempotent, transient failures use bounded
@@ -421,9 +502,15 @@ agentdebug hub push <trace-id> \
 Generate a debugging skill for a supported host runtime:
 
 ```bash
-agentdebug integrations skill --platform claude --target .claude/skills
+agentdebug integrations install --platform claude
+agentdebug integrations install --platform codex
+agentdebug integrations status --platform codex --json
 ```
 
+Generated Hermes and OpenClaw skills remain available through
+`agentdebug integrations skill --platform hermes|openclaw`. Refresh generated
+skills after upgrading so they use the shared `agentdebug run` contract.
+
 ### Optional: launch the local console
 
 Install the UI extra only when a visual inspection workflow is useful:
@@ -436,10 +523,45 @@ agentdebug serve \
   --port 7777
 ```
 
+For the integrated single-run path, AgentDebugX can manage the loopback server
+and return a readiness-checked deep link without opening a browser:
+
+```bash
+agentdebug run trace.json --profile standard --ui --json
+agentdebug ui ensure --run-id <run-id> --json
+agentdebug ui status --json
+```
+
+For a multi-record AgentErrorBench JSONL collection, either select one record
+or run the same durable workflow for every independent record:
+
+```bash
+agentdebug run trajectories.jsonl --trajectory-id <trajectory-id> --json
+agentdebug run trajectories.jsonl --batch --profile standard --json
+```
+
+`--batch` also accepts directories and recursively discovers independent JSON
+files. Each item receives its own run, trajectory, and report identity.
+Failures are isolated; a partial batch exits with code 3. A directly supplied
+JSONL file is split by row, so use `--batch` only when each row is a complete
+trajectory, not when the file is one event stream.
+
+For GUI RCA batches, continue using `python -m agentdebug.gui`; its OSWorld
+classification, failure filtering, parallel workers, memory, and output layout
+are intentionally separate from the generic `run --batch` contract.
+
+The run manifest, normalized trajectory, selected report, inline JSON, and
+`/runs/<run-id>` page retain the same `run_id`, `trace_id`, and `report_id`.
+The `deep` and `gui` profiles are explicitly LLM-backed; `quick` and
+`standard` never escalate to an LLM implicitly. UI startup failure is reported
+separately and does not change a completed diagnosis into a failed run.
+
 ## CLI Reference
 
 | Command | Purpose |
 | --- | --- |
+| `agentdebug run` | Create durable trajectory/report runs for one input or an explicit batch |
+| `agentdebug ui ensure` / `status` | Start, reuse, or inspect the readiness-checked local UI |
 | `agentdebug ingest` | Normalize an external trace export into AgentDebugX schema |
 | `agentdebug diagnose` | Run detection, attribution, and recovery planning |
 | `agentdebug batch ingest` | Normalize every JSON file or independent JSONL record |
@@ -449,7 +571,7 @@ agentdebug serve \
 | `agentdebug list` / `agentdebug show` | Inspect traces in a local store |
 | `agentdebug config` | Manage and test LLM endpoints and persistent HTTP runners |
 | `agentdebug hub` | Package, scrub, push, and pull Error Hub bundles |
-| `agentdebug integrations` | Generate external runtime integration assets |
+| `agentdebug integrations` | Generate, install, and validate host integration assets |
 | `agentdebug act` | Compatibility namespace for Hub and integration actions |
 | `agentdebug serve` / `agentdebug inspect` | Launch the optional local web console |
 | `agentdebug doctor` | Report optional dependency and configuration status |
@@ -471,7 +593,7 @@ src/agentdebug/rerun/        rerun plans, requests, branch comparison, and execu
 src/agentdebug/inspect/      traceback renderer and local inspection UI
 src/agentdebug/hub/          scrubbed failure bundle packaging and backends
 src/agentdebug/integrations/ host skill and runtime integration generators
-cua_debugger/                computer-use / OSWorld GUI root-cause tooling
+src/agentdebug/gui/          computer-use / OSWorld GUI root-cause analysis
 examples/                    runnable examples and demo traces
 docs/                        architecture, schema, and project assets
 ```
@@ -517,13 +639,56 @@ frontend. It is intentionally a surface layer:
 - local case and branch stores live in `inspect/ui/branch_store.py`
 - `inspect/ui/server.py` remains a compatibility import path
 
+### Launch from the CLI
+
+Install the optional UI dependencies, then point the server at an existing
+AgentDebugX trace store:
+
+```bash
+pip install "agentdebugx[ui]"
+
+agentdebug serve \
+  --store-sqlite .agentdebug/traces.sqlite \
+  --host 127.0.0.1 \
+  --port 7777
+```
+
+Open [http://127.0.0.1:7777](http://127.0.0.1:7777) in a browser. For a JSONL
+store, replace `--store-sqlite` with
+`--store-jsonl .agentdebug/traces.jsonl`. Keep the default loopback host unless
+the UI is deployed behind appropriate authentication and transport security.
+Place native trajectory and diagnostic-report JSON files under
+`.agentdebug/imports/`, then use **Sync imports** in the workspace to import
+new or changed files. Set `AGENTDEBUG_IMPORT_DIR` to use another server-owned
+directory.
+
+![AgentDebugX local inspection UI](docs/assets/UI.png)
+
 The UI can inspect traces, save typical error cases, prepare debug
-continuations, and invoke a server-controlled live runner. Set
+continuations, and invoke a server-controlled live runner. Rerun Composer is
+opened from a selected event and uses that event as its checkpoint. Set
 `AGENTDEBUG_RUNNER_URL` for the preferred persistent HTTP transport or
-`AGENTDEBUG_RERUN_COMMAND` for process compatibility. UI reruns default to a
-full `from_start` rollout; `from_event` requires runner capability plus the
-explicit server policy `AGENTDEBUG_UI_RERUN_POLICY=from_event`. The browser does
-not accept or persist runner commands, bearer tokens, or model API keys.
+`AGENTDEBUG_RERUN_COMMAND` for process compatibility. The selected runner must
+advertise or implement `from_event` checkpoint support. The browser does not
+accept or persist runner commands or bearer tokens; LLM API keys configured in
+the local UI are retained only for the current browser tab.
+
+OSWorld trajectories with locally available screenshot artifacts open in the
+read-only **Visual** view by default. Use the **Trace / Visual** control to
+switch without changing the selected event; the choice is remembered per trace
+for the current browser tab. Visual compares the selected action's **Before**
+state (an explicit input image or the immediately preceding event result) with
+all **After** images attached to the selected event; it never changes timeline
+selection or guesses across missing steps. Screenshots are served only through
+trace/event artifact IDs, and only when the resolved image remains inside the
+trajectory's recorded `metadata.source_dir`.
+
+**Discuss with Debugger** is available for every normalized trace format, not
+only CUA. Discussions are persisted locally, pinned to a report snapshot, cite
+canonical event IDs, and may produce an exportable report-revision draft.
+Discussion tools are read-only and drafts never overwrite stored diagnostic
+reports. The separate Streamlit app remains the tool for annotation,
+multi-reviewer assignment, and accuracy workflows.
 
 ## Privacy and Safety
 
@@ -581,8 +746,44 @@ python -m compileall -q src/agentdebug tests
 Build artifacts under `dist/` should not be committed. Generate them only for
 release workflows.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for test organization, optional CUA
-tests, quality checks, and pull request expectations.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for test organization, the optional GUI
+test suite, quality checks, and pull request expectations.
+
+## Citation
+
+```bibtex
+@article{agentdebug2025,
+  title={Where LLM Agents Fail and How They Can Learn From Failures},
+  author={Zhu, Kunlun and Liu, Zijia and Li, Bingxuan and Tian, Muxin and Yang Yingxuan and Zhang, Jiaxun and others},
+  journal={arXiv preprint arXiv:2509.25370},
+  year={2025}
+}
+```
+
+```bibtex
+@misc{zhu2026agentdebugxopensourcetoolkitfailure,
+      title={AgentDebugX: An Open-Source Toolkit for Failure Observability, Attribution, and Recovery in LLM Agents}, 
+      author={Kunlun Zhu and Xuyan Ye and Zhiguang Han and Yuchen Zhao and Bingxuan Li and Weijia Zhang and Muxin Tian and Xiangru Tang and Pan Lu and James Zou and Jiaxuan You and Heng Ji},
+      year={2026},
+      eprint={2607.18754},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2607.18754}, 
+}
+```
+
+```bibtex
+@misc{zhang2026cuadebugdiagnosingrepairingcomputeruse,
+      title={CUADebug: Diagnosing and Repairing Computer-Use Agent Failures},
+      author={Weijia Zhang and Kunlun Zhu and Zeyi Liu and Yinting Chen and Tianyi Ma and Jiateng Liu and Jiaxun Zhang and Bingxuan Li and Xiangru Tang and Heng Ji and Jiaxuan You},
+      year={2026},
+      eprint={2608.02643},
+      archivePrefix={arXiv},
+      primaryClass={cs.SE},
+      url={https://arxiv.org/abs/2608.02643},
+}
+```
+
 
 ## License