execweave 0.8.1__tar.gz → 0.8.3__tar.gz

execweave-0.8.3/.github/workflows/provider-capability-stage-integrity.yml

@@ -0,0 +1,98 @@
+name: Provider Capability Stage Integrity
+
+# No path filter. This job guards release red lines — the disabled CONNECT handler,
+# the existing test set, the conversation completeness vocabulary, release metadata —
+# so it must run on every pull request. A filter listing only the capability-probe
+# files would arm the guard exactly when the guarded files are NOT the ones changing:
+# a pull request that weakens http_proxy.py, deletes a test, or bumps the version
+# while touching none of those paths would skip this job entirely.
+on:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      baseline_ref:
+        description: Base commit or ref used to reconstruct baseline test node IDs
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  integrity:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out pull request
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Validate stage integrity
+        shell: bash
+        env:
+          BASELINE_REF: "${{ github.event.pull_request.base.sha || inputs.baseline_ref }}"
+          HEAD_REF: "${{ github.head_ref }}"
+        run: |
+          args=(--baseline-ref "$BASELINE_REF")
+          # A release/* branch may advance the release metadata assertions, but the
+          # branch name alone is not the grant: the whole 0.8.x series of feature work
+          # lives under release/*, and an allowance those branches never use is an open
+          # allowance, which the checker refuses. The file has to actually change.
+          release_metadata_changed=""
+          if git diff --name-only "$BASELINE_REF...HEAD" \
+              | grep -qx 'tests/test_v069_dashboard_release.py'; then
+            release_metadata_changed=yes
+          fi
+          if [[ "$HEAD_REF" == release/* && -n "$release_metadata_changed" ]]; then
+            args+=(--allow-test-change "tests/test_v069_dashboard_release.py=release metadata assertions may advance only on a release/* pull request; the historical test name remains stable because the node-ID floor refuses renames")
+          fi
+          # PR #25 changes one historical source assertion only because tool traffic is
+          # appended inside the same render pass. Grant that exact exception only to the
+          # exact PR #25 branch and only while the file actually differs from the base.
+          # Once PR #25 lands, future branches cannot inherit this allowance merely by
+          # changing the same test file.
+          conversation_focus_changed=""
+          if git diff --name-only "$BASELINE_REF...HEAD" \
+              | grep -qx 'tests/test_conversation_agent_focus.py'; then
+            conversation_focus_changed=yes
+          fi
+          if [[ "$HEAD_REF" == "release/0.8.3-graph-ergonomics" && -n "$conversation_focus_changed" ]]; then
+            args+=(--allow-test-change "tests/test_conversation_agent_focus.py=PR #25 only: surfacing tool traffic appends one more card inside the same render pass, so the source assertion that pinned the final line names the new line. The test ID and subject are unchanged")
+          fi
+          # AUD-001 repairs a historical assertion that deliberately characterized the
+          # cross-session root merge as a known limitation. Keep the node ID stable, and
+          # grant the assertion change only on the dedicated R1 branch or the exact PR #25
+          # integration branch that may absorb it. The file must actually differ, so this
+          # cannot become a standing exemption for unrelated work or future release lines.
+          conversation_identity_changed=""
+          if git diff --name-only "$BASELINE_REF...HEAD" \
+              | grep -qx 'tests/test_conversation_identity_merge.py'; then
+            conversation_identity_changed=yes
+          fi
+          if [[ -n "$conversation_identity_changed" ]] \
+              && { [[ "$HEAD_REF" == "fix/0.8.3-conversation-identity" ]] \
+                   || [[ "$HEAD_REF" == "release/0.8.3-graph-ergonomics" ]]; }; then
+            args+=(--allow-test-change "tests/test_conversation_identity_merge.py=AUD-001 only: the historical root-collision assertion is no longer correct after derived presentation thread ids stop acting as cross-execution identity; the original test node ID is retained and the assertion now requires isolation")
+          fi
+          # R2 changes the historical llama.cpp request-ID assertion because native
+          # request IDs are no longer globally authoritative: the endpoint scope is now
+          # part of the graph request identity. Grant only this branch/file combination.
+          model_runtime_identity_changed=""
+          if git diff --name-only "$BASELINE_REF...HEAD" \
+              | grep -qx 'tests/test_model_runtime.py'; then
+            model_runtime_identity_changed=yes
+          fi
+          if [[ "$HEAD_REF" == "fix/0.8.3-inference-endpoint-identity" \
+              && -n "$model_runtime_identity_changed" ]]; then
+            args+=(--allow-test-change "tests/test_model_runtime.py=AUD-002 only: the historical llama.cpp request ID assertion now includes the sanitized endpoint scope; the test node ID and runtime privacy contract are unchanged")
+          fi
+          python scripts/check_release_stage_integrity.py "${args[@]}"

execweave-0.8.3/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.5
+Name: execweave
+Version: 0.8.3
+Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
+Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
+Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
+Project-URL: Documentation, https://github.com/Irish-kw/ExecWeave#documentation
+Project-URL: Issues, https://github.com/Irish-kw/ExecWeave/issues
+Author: ExecWeave contributors
+License: PolyForm Noncommercial License 1.0.0
+        
+        This software is licensed under the PolyForm Noncommercial License 1.0.0.
+        The complete license terms are available at:
+        https://polyformproject.org/licenses/noncommercial/1.0.0
+        
+        Required Notice: Copyright (c) 2026 GWW
+        
+        Commercial use is not permitted under this license. Any commercial use,
+        including use in or for a commercial product or service, requires a separate
+        written commercial license from the licensor.
+        
+        For the avoidance of doubt, this license change applies to versions released
+        under these terms. Earlier versions that were already distributed under the
+        MIT License remain available under the license terms that accompanied those
+        versions.
+License-File: LICENSE
+Keywords: ai-agents,execution-graph,observability,provenance,runtime,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: Other/Proprietary License
+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: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: psutil>=5.9
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.44; extra == 'e2e'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=6.0; extra == 'release'
+Description-Content-Type: text/markdown
+
+# ExecWeave
+
+<!-- i18n-nav:start -->
+<p align="center">
+  <strong>English</strong> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.ja.md">日本語</a> |
+  <a href="README.ko.md">한국어</a> |
+  <a href="README.fr.md">Français</a> |
+  <a href="README.de.md">Deutsch</a> |
+  <a href="README.ru.md">Русский</a>
+</p>
+<!-- i18n-nav:end -->
+
+<p align="center">
+  <a href="https://pypi.org/project/execweave/"><img src="https://img.shields.io/pypi/v/execweave" alt="PyPI"></a>
+  <a href="https://github.com/Irish-kw/ExecWeave/actions/workflows/ci.yml"><img src="https://github.com/Irish-kw/ExecWeave/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue" alt="License"></a>
+</p>
+
+**See what AI agents actually do on your machine.**
+
+ExecWeave is a source-available, local-first observability project that turns AI-agent activity into an interactive execution graph while keeping observed evidence, provider-supplied content, and derived inference explicitly separated.
+
+> **Event is ground truth. The graph is a materialized view.**
+
+<p align="center">
+  <img src="docs/assets/codex.gif" alt="ExecWeave animated live demo" width="100%">
+</p>
+
+This README documents **v0.8.3**.
+
+## Why ExecWeave
+
+- **One local inspection surface.** Live runs, completed runs, and standalone `viewer.html` use the same dashboard renderer for graph, logs, conversations, and node details.
+- **Evidence-aware by design.** Direct observations stay distinguishable from identity links, conservative inference, and causal claims.
+- **Provider-aware without inventing hidden behavior.** ExecWeave uses the strongest routing and identity evidence a provider actually exposes; missing evidence stays missing.
+- **Useful beyond one Agent.** OS-runtime telemetry can wrap any local command, while provider adapters add richer semantics when supported.
+
+## Install
+
+Install the latest published package from PyPI:
+
+```bash
+python -m pip install -U execweave
+```
+
+For development:
+
+```bash
+git clone https://github.com/Irish-kw/ExecWeave.git
+cd ExecWeave
+python -m pip install -e ".[dev]"
+```
+
+## 60-second quick start
+
+Live OS-runtime telemetry works with **any local command**. These Agent/runtime names are examples, not a whitelist.
+
+```bash
+execweave live --open -- claude
+execweave live --open -- codex
+execweave live --open -- antigravity
+execweave live --open -- cursor
+execweave live --open -- opencode
+execweave live --open -- ollama serve
+execweave live --open -- python my_agent.py
+```
+
+> **Approve the hook when prompted.** On the first provider-integrated run, the Agent/IDE may ask whether ExecWeave may enable its local hook integration. Choose **Allow / Yes**. Without approval, OS-runtime telemetry can still work, but provider-level tool, model, conversation, and supplied-content visibility may be reduced or unavailable.
+
+Google Antigravity currently uses the `agy` CLI command; ExecWeave also accepts `antigravity` as a friendly alias and resolves it to `agy`. For Cursor, `execweave live --open -- cursor` first tries a normal PATH launcher, then falls back to the standard desktop application binary on macOS and Windows.
+
+Build finalized run artifacts with:
+
+```bash
+execweave record --open -- python my_agent.py
+```
+
+For a detached overview while keeping the Agent interactive in the launch terminal:
+
+```bash
+execweave top -- codex
+```
+
+## Dashboard
+
+ExecWeave keeps Live, finished, and standalone viewing on the same dashboard model instead of switching renderers at the end of a run.
+
+- **Execution graph:** agents, processes, files, network endpoints, tools, model/runtime entities, and supported semantic relations.
+- **Conversation rounds:** the newest round is immediately readable; older rounds remain individually reachable instead of being overwritten by newer replies.
+- **Node details:** process nodes show command/PID context, file nodes show path/history context, and network nodes show endpoint/process context.
+- **Large-run readability:** per-type folding keeps recent members visible while older members collapse into an inspectable aggregate. Set the threshold with `--fold-budget N`.
+- **Selection clarity:** multi-agent layout keeps a stable root/child hierarchy and de-emphasizes unrelated edges when an agent is selected.
+
+### v0.8.3 dashboard changes
+
+v0.8.3 focuses on making dense and multi-round runs readable without changing raw evidence:
+
+- conversation panels are round-based instead of pairing one old prompt with one new reply;
+- explicit reader open/closed state survives the 800 ms Live refresh;
+- subagent responses remain attributed to the agent that produced them;
+- process, file, and network selections no longer open empty detail panels;
+- high-cardinality node types fold under a configurable budget rather than overwhelming the graph;
+- lifecycle return edges no longer distort root/child rank, and shared tool/model traffic uses clearer routed geometry.
+
+These are presentation-layer changes. Raw graph evidence is unchanged, and Live, finished, and `viewer.html` continue to share one renderer.
+
+## Supported integrations
+
+| Integration | OS-runtime observation when launched under ExecWeave | Specialized evidence |
+| --- | --- | --- |
+| Claude Code | Yes | native hooks + full-fidelity supplied hook content + exact subagent results when exposed |
+| OpenAI Codex | Yes | lifecycle hooks + validated rollout transcripts + agent-local task/message/final-response routing |
+| Google Antigravity / Antigravity CLI | Yes | passive native hooks + validated conversation/subagent routing where exposed |
+| Cursor | Yes | native hooks + exact subagent task/summary routing when exposed |
+| OpenCode | Yes | project plugin + session/task routing + full-fidelity supplied plugin content |
+| Ollama | Yes | `execweave-model-runtime event/exchange/probe --runtime ollama` |
+| llama.cpp | Yes | `execweave-model-runtime event/exchange/probe --runtime llamacpp` |
+| vLLM | Yes | `execweave-model-runtime event/exchange/probe --runtime vllm` |
+| LM Studio | Only when the local process is launched under ExecWeave | `execweave-model-runtime event/exchange/probe --runtime lmstudio` |
+| LiteLLM Proxy | Yes when the configured proxy is launched under ExecWeave | metadata-oriented gateway callback/event integration |
+| OpenRouter | Observe the local client, not the remote service process | `execweave-inference-gateway event/exchange/generation --gateway openrouter` |
+
+Stable provider identifiers such as Cursor `tool_use_id`, Codex rollout thread identity, or OpenCode `sessionID + callID` prove logical provider identity; they are not OS PIDs. Cross-agent content is shown only when the provider exposes an explicit route, delegation, or result. Gateways or local runtimes that expose only root request/response traffic remain root-only; ExecWeave does not fabricate subagents or hidden routing.
+
+OpenRouter `exchange` is caller-supplied request+response evidence, not transparent wire interception. LiteLLM Proxy remains a narrower metadata-oriented integration in the current baseline. Legacy Gemini CLI entry points remain packaged for compatibility, but new Google CLI usage should use Antigravity (`agy`).
+
+## Evidence model
+
+ExecWeave keeps evidence layers separate instead of flattening them into one trace:
+
+```text
+Agent / IDE semantic + supplied content evidence
+          ↓
+Inference gateway / routing evidence
+          ↓
+Model runtime / inference-server evidence
+          ↓
+OS runtime evidence: process / file / network
+```
+
+A relationship is causal only when the underlying telemetry supports that claim. Conservative Tool → Process bridges stay marked as derived evidence:
+
+```text
+inferred: true
+causal: false
+```
+
+Exact shared request identity across Gateway and Model Runtime is identity evidence, not causal evidence:
+
+```text
+identity_exact: true
+inferred: false
+causal: false
+```
+
+Ambiguity produces no edge.
+
+### Full-fidelity supplied content
+
+Since **v0.6.9**, supported integration points can preserve the complete value explicitly supplied by the provider/hook/API in a local SHA-256 content-addressed store while the semantic event stream keeps a reference:
+
+```text
+<run-root>/content/sha256/<sha256>.<json|txt|bin>
+```
+
+Depending on the integration, preserved values can include prompts/messages, request/response objects, tool inputs/results, assistant responses, explicitly exposed reasoning/thinking text, shell/MCP output, and file content supplied by provider hooks.
+
+`complete_from_source: true` means ExecWeave stored the complete value delivered by that integration point. It does **not** mean ExecWeave observed hidden model state, provider-side stages that were never exposed, an unseen final wire request, or bytes it did not intercept.
+
+## Common commands
+
+### Agent / IDE recorders
+
+```bash
+execweave-claude-record --open -- claude
+execweave-codex-record --open -- codex
+execweave-antigravity-record --open -- antigravity
+execweave-cursor-record --open -- cursor
+execweave-opencode-plugin --install
+execweave-opencode-record --open -- opencode
+```
+
+### Gateways and model runtimes
+
+```bash
+execweave-inference-gateway event --gateway openrouter --sidecar gateway.jsonl
+execweave-inference-gateway exchange --gateway openrouter --sidecar gateway.jsonl
+execweave-inference-gateway event --gateway litellm --sidecar gateway.jsonl
+
+execweave-model-runtime event --runtime ollama --sidecar model-runtime.jsonl
+execweave-model-runtime exchange --runtime ollama --sidecar model-runtime.jsonl
+execweave-model-runtime probe --runtime ollama --sidecar model-runtime.jsonl
+```
+
+`event` is response-only evidence. `exchange` stores a caller-supplied request+response object and does not assert transparent interception. Runtime catalog relations keep their source-specific meanings: `LOADED_MODEL`, `SERVES_MODEL`, and `ADVERTISES_MODEL` are not interchangeable. LM Studio catalog visibility remains `ADVERTISES_MODEL`, not proof that weights were resident in memory.
+
+### Runtime, graph, security, and integrity
+
+```bash
+execweave doctor
+execweave run --backend portable -- your-command
+execweave run --backend strace -- your-command
+execweave graph-summary run.graph.json
+execweave graph-filter run.graph.json --causal-only --output causal.graph.json
+execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
+execweave path run.graph.json SOURCE TARGET --causal-only
+execweave analyze run.graph.json --output analysis.json
+execweave-rule-pack graph.json --rule-pack local-policy.json --output report.json
+execweave-integrity seal .execweave/runs/<run-id>
+execweave-integrity verify .execweave/runs/<run-id>
+```
+
+Security findings carry an evidence grade independently from severity. Current grades are `A`, `B`, `C`, `D`, and `U`; they are evidence-strength categories, not probabilities or trust scores. Rule packs are bounded, explainable single-edge observation policies and cannot execute third-party code or prove byte-level exfiltration.
+
+## Run artifacts
+
+A provider-integrated run may contain:
+
+```text
+.execweave/runs/<run-id>/
+├── events.jsonl
+├── graph.json
+├── viewer.html
+├── semantic.jsonl
+├── content/sha256/...
+├── conversations.md
+├── conversations.json
+├── events.semantic.jsonl
+├── graph.semantic.json
+├── viewer.semantic.html
+├── events.correlated.jsonl
+├── graph.correlated.json
+├── viewer.correlated.html
+└── integrity.json            # after an explicit seal
+```
+
+Derived correlation never rewrites raw runtime or provider sidecar evidence.
+
+## Limits and privacy
+
+- The portable collector runs on Linux, macOS, and Windows. Portable filesystem observation is session-correlated rather than process-causal, and polling can miss sufficiently short-lived activity.
+- Linux also has a syscall-backed `strace` reference backend with stronger process-attributed syscall evidence for supported executions.
+- Native Linux eBPF, Windows ETW, and macOS Endpoint Security collectors remain planned work, not current claims.
+- Full-fidelity provider content can preserve secrets embedded in prompts, tool values, model responses, shell output, or supplied files. ExecWeave is **not** a general secret scanner or content redactor.
+- Conversation isolation is an attribution/display rule, not a redaction boundary. If a provider explicitly routes content between agents, that content can legitimately appear at participating endpoints.
+- Commands, paths, endpoints, identifiers, model metadata, prompts, tool values, and content blobs can all be sensitive. Review the entire run directory before sharing it.
+- A local integrity seal detects file changes relative to its manifest, but it is not adversary-resistant when both evidence and manifest remain inside the same writable trust boundary.
+
+## Performance
+
+ExecWeave includes bounded filesystem/viewer protections, incremental Live JSONL tailing, large-graph safety guards, detached Top, and provisional live sidecars for configured provider integrations.
+
+The reproducible incremental `GraphAccumulator` reference result reaches **164,273 ev/s** at 1M synthetic events on the documented GitHub Actions workload. This is a graph-accumulation benchmark, not end-to-end collector/browser throughput.
+
+Run the package-level benchmarks on a representative host/workload:
+
+```bash
+execweave-overhead --iterations 7 --strace auto --output-json benchmark-results.json
+execweave-scalability
+```
+
+Reference data and methodology live in [`docs/benchmarks/`](docs/benchmarks/).
+
+## Documentation
+
+| Area | Documents |
+| --- | --- |
+| Runtime and graph | [`Phase 1 — Runtime Collection`](docs/phase-1-runtime-collection.md) · [`Phase 2 — Execution Graph`](docs/phase-2-execution-graph.md) · [`Live Graph`](docs/live-graph.md) · [`Semantic Telemetry`](docs/semantic-telemetry.md) |
+| Agent / IDE integrations | [`Claude Code`](docs/claude-code-hooks.md) · [`OpenAI Codex`](docs/codex-hooks.md) · [`Google Antigravity`](docs/antigravity-hooks.md) · [`Cursor`](docs/cursor-hooks.md) · [`OpenCode`](docs/opencode-plugin.md) |
+| Gateways and runtimes | [`Inference Gateway / OpenRouter / LiteLLM`](docs/inference-gateway.md) · [`Model Runtime / Ollama / llama.cpp / vLLM / LM Studio`](docs/model-runtime.md) |
+| Trust and analysis | [`Runtime Threat Model`](docs/runtime-threat-model.md) · [`Evidence Grades`](docs/evidence-grades.md) · [`Rule Packs`](docs/rule-packs.md) · [`Run Integrity`](docs/run-integrity.md) · [`Security Analysis`](docs/security-analysis.md) |
+| Performance | [`Benchmarks`](docs/benchmarks/README.md) |
+
+## Contributing
+
+Contributions are welcome, especially around native OS collectors, Agent/IDE adapters, inference gateways, model runtimes, evidence/correlation methods, privacy/redaction, graph UX, multi-agent conversation attribution, and performance evaluation.
+
+## License
+
+Starting with v0.6.8, ExecWeave is licensed under the **PolyForm Noncommercial License 1.0.0**. Noncommercial use, modification, and redistribution are permitted under its terms. Commercial use requires a separate written commercial license from the licensor. See [`LICENSE`](LICENSE).