agentledger-runtime 1.0.0__tar.gz

agentledger_runtime-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,264 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Compile
+        run: PYTHONPYCACHEPREFIX=/tmp/agentledger-pycache PYTHONPATH=src python -m compileall -q src tests examples
+
+      - name: Test
+        run: PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m unittest discover -s tests -q
+
+      - name: ResourceWarning-sensitive tests
+        run: PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src PYTHONTRACEMALLOC=10 python -W default::ResourceWarning -m unittest discover -s tests -q
+
+      - name: Contract export is valid JSON
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger contract export > /tmp/agentledger-contract.json
+          python -m json.tool /tmp/agentledger-contract.json >/dev/null
+
+      - name: Migration DDL smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger migrate ddl --dialect sqlite >/tmp/agentledger-sqlite.sql
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger migrate ddl --dialect postgres >/tmp/agentledger-postgres.sql
+
+      - name: State conformance smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger state conformance --backend sqlite >/tmp/agentledger-state-conformance.json
+          python -m json.tool /tmp/agentledger-state-conformance.json >/dev/null
+
+      - name: Blob conformance smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger blob conformance --backend local >/tmp/agentledger-blob-conformance.json
+          python -m json.tool /tmp/agentledger-blob-conformance.json >/dev/null
+
+      - name: Worker conformance smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger worker conformance --backend sqlite --concurrent >/tmp/agentledger-worker-conformance.json
+          python -m json.tool /tmp/agentledger-worker-conformance.json >/dev/null
+
+      - name: Root conformance smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-ci-conformance conformance >/tmp/agentledger-conformance.json
+          python -m json.tool /tmp/agentledger-conformance.json >/dev/null
+
+      - name: Adapter conformance smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger adapter conformance --kind python-function >/tmp/agentledger-adapter-python.json
+          python -m json.tool /tmp/agentledger-adapter-python.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger adapter conformance --kind langchain >/tmp/agentledger-adapter-langchain.json
+          python -m json.tool /tmp/agentledger-adapter-langchain.json >/dev/null
+
+      - name: Worker serve smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-worker-serve worker serve examples/transient_retry --max-loops 5 --idle-sleep-seconds 0 >/tmp/agentledger-worker-serve.json
+          python -m json.tool /tmp/agentledger-worker-serve.json >/dev/null
+
+      - name: Tool catalog smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger tools manifest --example examples/docs >/tmp/agentledger-tools.json
+          python -m json.tool /tmp/agentledger-tools.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger tools manifest --example examples/docs --format openai >/tmp/agentledger-openai-tools.json
+          python -m json.tool /tmp/agentledger-openai-tools.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger tools manifest --example examples/media_stream >/tmp/agentledger-media-tools.json
+          python -m json.tool /tmp/agentledger-media-tools.json >/dev/null
+
+      - name: Failure injection smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-failure failure inject --scenario all >/tmp/agentledger-failure.json
+          python -m json.tool /tmp/agentledger-failure.json >/dev/null
+
+      - name: Runtime boundary lint smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger lint boundary examples tests --exclude tests/test_runtime.py >/tmp/agentledger-boundary-lint.json
+          python -m json.tool /tmp/agentledger-boundary-lint.json >/dev/null
+
+      - name: Example smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/hello_world/hello.py >/tmp/agentledger-example-hello.txt
+          test -s /tmp/agentledger-example-hello.txt
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/autogen/basic_agent.py >/tmp/agentledger-example-autogen.json
+          python -m json.tool /tmp/agentledger-example-autogen.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/crewai/basic_crew.py >/tmp/agentledger-example-crewai.json
+          python -m json.tool /tmp/agentledger-example-crewai.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/langchain/basic_runnable.py >/tmp/agentledger-example-langchain.json
+          python -m json.tool /tmp/agentledger-example-langchain.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/langgraph/basic_graph.py >/tmp/agentledger-example-langgraph.json
+          python -m json.tool /tmp/agentledger-example-langgraph.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/llamaindex/basic_query.py >/tmp/agentledger-example-llamaindex.json
+          python -m json.tool /tmp/agentledger-example-llamaindex.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/media_stream/basic_media_stream.py >/tmp/agentledger-example-media.json
+          python -m json.tool /tmp/agentledger-example-media.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/media_stream/managed_tool.py >/tmp/agentledger-example-media-tool.json
+          python -m json.tool /tmp/agentledger-example-media-tool.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/mcp_context/basic_context_server.py >/tmp/agentledger-example-mcp-context.json
+          python -m json.tool /tmp/agentledger-example-mcp-context.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/mcp_tool/basic_tool.py >/tmp/agentledger-example-mcp.json
+          python -m json.tool /tmp/agentledger-example-mcp.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/openai_agents/basic_agent.py >/tmp/agentledger-example-openai-agents.json
+          python -m json.tool /tmp/agentledger-example-openai-agents.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/sandbox/command_tool.py >/tmp/agentledger-example-sandbox.json
+          python -m json.tool /tmp/agentledger-example-sandbox.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/tool_catalog/basic_catalog.py >/tmp/agentledger-example-tool-catalog.json
+          python -m json.tool /tmp/agentledger-example-tool-catalog.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python examples/semantic_kernel/basic_kernel.py >/tmp/agentledger-example-semantic-kernel.json
+          python -m json.tool /tmp/agentledger-example-semantic-kernel.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-ci-worker-run worker-run examples/transient_retry >/tmp/agentledger-example-worker-run.json
+          python -m json.tool /tmp/agentledger-example-worker-run.json >/dev/null
+
+      - name: Evidence regression smoke
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression run examples/side_effect_idempotency >/tmp/agentledger-regression-run.json
+          RUN_ID=$(python -c 'import json; print(json.load(open("/tmp/agentledger-regression-run.json"))["run_id"])')
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression timetravel "$RUN_ID" --include-diffs --include-states --html /tmp/agentledger-timetravel.html >/tmp/agentledger-timetravel-report.json
+          test -s /tmp/agentledger-timetravel.html
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression cost report "$RUN_ID" >/tmp/agentledger-cost-report.json
+          python -m json.tool /tmp/agentledger-cost-report.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression failure report "$RUN_ID" >/tmp/agentledger-failure-report.json
+          python -m json.tool /tmp/agentledger-failure-report.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression review checklist "$RUN_ID" --max-total-usd 1.0 >/tmp/agentledger-review.json
+          python -m json.tool /tmp/agentledger-review.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression trace "$RUN_ID" --format otlp --out /tmp/agentledger-trace.otlp.json >/tmp/agentledger-trace-otlp.json
+          python -m json.tool /tmp/agentledger-trace.otlp.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression evidence "$RUN_ID" --out /tmp/agentledger-golden.json >/tmp/agentledger-evidence-file.json
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression evidence "$RUN_ID" --dir /tmp/agentledger-current >/tmp/agentledger-evidence-dir.json
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression evidence "$RUN_ID" --html /tmp/agentledger-evidence.html >/tmp/agentledger-evidence-html.json
+          test -s /tmp/agentledger-evidence.html
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger divergence /tmp/agentledger-golden.json /tmp/agentledger-current --evidence-paths >/tmp/agentledger-divergence.json
+          python -m json.tool /tmp/agentledger-divergence.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger evidence-regression /tmp/agentledger-golden.json /tmp/agentledger-current >/tmp/agentledger-evidence-regression.json
+          python -m json.tool /tmp/agentledger-evidence-regression.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression corpus add side-effect /tmp/agentledger-golden.json >/tmp/agentledger-corpus-add.json
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression corpus seed minimal-success >/tmp/agentledger-corpus-seed.json
+          python -m json.tool /tmp/agentledger-corpus-seed.json >/dev/null
+          PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m agentledger --root /tmp/agentledger-regression corpus check side-effect /tmp/agentledger-current >/tmp/agentledger-corpus-eval.json
+          python -m json.tool /tmp/agentledger-corpus-eval.json >/dev/null
+
+  postgres-integration:
+    name: Postgres integration
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: agentledger
+          POSTGRES_PASSWORD: agentledger
+          POSTGRES_DB: agentledger
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U agentledger -d agentledger"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Postgres optional dependency
+        run: python -m pip install ".[postgres]"
+
+      - name: Run real Postgres conformance
+        env:
+          AGENTLEDGER_RUN_POSTGRES_INTEGRATION: "1"
+          AGENTLEDGER_POSTGRES_DSN: postgresql://agentledger:agentledger@127.0.0.1:5432/agentledger
+          AGENTLEDGER_POSTGRES_SCHEMA: agentledger_ci
+          PYTHONDONTWRITEBYTECODE: "1"
+          PYTHONPATH: src
+        run: python -m unittest tests.test_postgres_integration -v
+
+  minio-integration:
+    name: MinIO integration
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install S3 optional dependency
+        run: python -m pip install ".[s3]"
+
+      - name: Start MinIO
+        run: |
+          docker run -d --name agentledger-minio \
+            -p 9000:9000 \
+            -e MINIO_ROOT_USER=agentledger \
+            -e MINIO_ROOT_PASSWORD=agentledger123 \
+            minio/minio:RELEASE.2025-04-22T22-12-26Z server /data
+          python - <<'PY'
+          import time
+          import urllib.request
+
+          for _ in range(60):
+              try:
+                  urllib.request.urlopen("http://127.0.0.1:9000/minio/health/ready", timeout=2).read()
+                  break
+              except Exception:
+                  time.sleep(1)
+          else:
+              raise SystemExit("MinIO did not become ready")
+          PY
+
+      - name: Create bucket
+        env:
+          AWS_ACCESS_KEY_ID: agentledger
+          AWS_SECRET_ACCESS_KEY: agentledger123
+          AWS_DEFAULT_REGION: us-east-1
+        run: |
+          python - <<'PY'
+          import boto3
+
+          client = boto3.client(
+              "s3",
+              endpoint_url="http://127.0.0.1:9000",
+              region_name="us-east-1",
+              aws_access_key_id="agentledger",
+              aws_secret_access_key="agentledger123",
+          )
+          client.create_bucket(Bucket="agentledger-runs")
+          PY
+
+      - name: Run real MinIO conformance
+        env:
+          AGENTLEDGER_RUN_S3_INTEGRATION: "1"
+          AGENTLEDGER_S3_BUCKET: agentledger-runs
+          AGENTLEDGER_S3_PREFIX: ci/blobs
+          AGENTLEDGER_S3_ENDPOINT_URL: http://127.0.0.1:9000
+          AGENTLEDGER_S3_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: agentledger
+          AWS_SECRET_ACCESS_KEY: agentledger123
+          PYTHONDONTWRITEBYTECODE: "1"
+          PYTHONPATH: src
+        run: python -m unittest tests.test_s3_integration -v

agentledger_runtime-1.0.0/.gitignore

@@ -0,0 +1,38 @@
+.agentledger/
+*.db
+*.sqlite
+*.sqlite3
+
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+.DS_Store
+**/.DS_Store
+
+# Local notes, research dumps, and generated reports that should not ship.
+AI_Agent_Runtime_开源项目构想.md
+*.pdf
+*.docx
+*.pptx
+*.pages
+*.key
+evidence/
+evidence*.html
+time-travel*.html
+
+# Local external installer/download artifacts.
+rce

agentledger_runtime-1.0.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to AgentLedger will be documented in this file.
+
+This project follows semantic versioning for the stable runtime-core contract. Optional adapters can still carry preview or experimental status.
+
+## Unreleased
+
+### Changed
+
+- Removed public `eval` CLI aliases in favor of `evidence-check`, `evidence-regression`, and `corpus check`, keeping full eval systems outside runtime-core.
+- Clarified the v1.0 roadmap section as implemented for Python runtime-core, with media/stream contracts still marked preview.
+- Changed the PyPI distribution name to `agentledger-runtime` while keeping the import package and CLI as `agentledger`.
+
+## 1.0.0
+
+### Added
+
+- Maturity model and release-readiness documentation.
+- Roadmap scope map for stable runtime-core, optional adapters, and external evidence consumers.
+- Architecture overview for runtime layers, core modules, invariants, and adapter boundaries.
+- Experimental psycopg-backed Postgres StateStore path with env/CLI configuration, schema isolation, JSONB handling, connection-injection conformance, and opt-in real-service smoke test.
+- Experimental S3/MinIO BlobStore adapter with optional boto3 loading, env/CLI configuration, injected-client support, BlobStore conformance coverage, and opt-in real-service smoke test.
+- Store-level artifact creation to remove SQLite connection leakage from `AgentContext`.
+- Language-neutral runtime contract fixture for future Rust, TypeScript, and Go implementations.
+- Storage migration baseline with SQLite `schema_migrations`, Postgres migration status/apply, and DDL export.
+- Kubernetes/gVisor sandbox dry-run and `kubectl`-gated execution path.
+- Evidence regression CLI for golden-vs-current evidence gates across final state, event types, Tool Ledger statuses, and cost deltas.
+- Runtime boundary lint CLI for common direct shell, HTTP, SDK, cloud, and model calls that bypass `ctx.call_tool`.
+- Dependency-free OTLP JSON trace exporter, CLI `trace --format otlp`, and optional OTLP/JSON collector POST.
+- Failure injection suite and CLI for local crash, retry, lease fencing, and cancellation probes.
+- Runnable dependency-free LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, LlamaIndex, Semantic Kernel, MCP-style tool/context, tool catalog, and sandbox command examples.
+- Roadmap entries for media artifact and event stream runtime support.
+- LangGraph-compatible dependency-free checkpointer facade with `put`, `get`, `get_tuple`, `list`, and `put_writes`.
+- Versioning/compatibility policy and adapter certification checklist.
+- Golden evidence corpus and `agentledger corpus add/list/check` repro harness.
+- Dependency-free LangChain, CrewAI, AutoGen, OpenAI Agents SDK, LlamaIndex, and Semantic Kernel method facades.
+- Read-only backup readiness checker and CLI `agentledger backup check <run_id>`.
+- Tool schema/catalog DX with dependency-free schema subset validation and `agentledger tools manifest`.
+- Static time-travel HTML debug export via `agentledger timetravel --html` and `agentledger debug --html`.
+- Framework adapter conformance runner and CLI fixtures for dependency-free adapter certification smoke.
+- Tool catalog example showing `Runtime.tool(...)`, schema validation, AgentLedger manifest export, and OpenAI-compatible tool descriptors.
+- Read-only cost attribution report and CLI `agentledger cost report <run_id>`.
+- Read-only failure attribution report and CLI `agentledger failure report <run_id>`.
+- Replay/rerun divergence report and CLI `agentledger divergence`.
+- Adversarial review checklist and release gate CLI `agentledger review checklist`.
+- Static evidence HTML report via `agentledger evidence --html`.
+- Dependency-free MCP tool/context server fixtures and `MCPContextAdapter`.
+- CI real-service conformance jobs for Postgres and MinIO optional adapters.
+- Built-in golden corpus seed fixture via `agentledger corpus seed minimal-success`.
+- Preview media and event-stream artifact contracts with `MediaArtifact`, `MediaMetadata`, `ArtifactLineage`, `StreamChunkRef`, `EventStreamCheckpoint`, context helpers, evidence counts, language-neutral contract entries, and a dependency-free example.
+- Media/stream tool schema conventions for `audio.transcribe`, `video.extract_frames`, `frame.describe`, `video.summarize`, `stream.consume`, and `stream.emit`, including CLI manifest export.
+- Evidence bundle media/stream indexes and replay artifact validation/counts for archived media manifests and stream checkpoints.
+- Runtime-managed media tool example showing `video.extract_frames` through ToolGateway, Tool Ledger, media artifact creation, and evidence export.
+- Adversarial review checks for media artifact refs and stream checkpoint offsets.
+- Evidence diff and divergence dimensions for media artifacts and stream checkpoints.
+- Evidence regression gates for media artifact refs and stream checkpoint changes, with CLI allow flags.
+- Backup readiness checks for media/stream evidence shape and nested `blob://` refs inside artifact metadata.
+- Retention planning now reports media artifact counts, stream checkpoint counts, and protected nested blob refs before any future compaction.
+- Trace export now includes media artifact and stream checkpoint spans in addition to event spans.
+- Media runtime conformance runner covering media evidence, replay, evidence regression, review, trace, and Tool Ledger chains.
+- Transient retry worker demo documentation for `worker-run` and `worker serve`.
+- Docs tool catalog fixture documentation for `agentledger tools manifest --example examples/docs`.
+- Release checklist documentation covering local gates, example smoke, optional service-backed checks, evidence gates, and release-note requirements.
+- Formal documentation index, detailed usage guide, detailed design/implementation guide, Chinese documentation entrypoints, and SVG runtime architecture diagram.
+- CLI parser smoke coverage for documented commands, including nested commands and global `--policy` usage.
+- Packaging metadata coverage for the `agentledger` console script, supported Python versions, README metadata, and optional dependency groups.
+- Media/stream adapter boundary and certification guidance for durable refs, lineage, checkpoints, replay, and evidence export.
+
+### Changed
+
+- CI now compiles examples, runs ResourceWarning-sensitive tests, executes root conformance, checks media tool manifests, and smokes media/worker examples.
+- README and CONTRIBUTING release checks now point to the shared release checklist and include ResourceWarning, conformance, lint, and contract gates.
+- Python package classifiers now include Python 3.12, Python 3 only, OS independence, and Python library metadata.
+
+### Fixed
+
+- Postgres injected connection ownership is now explicit, preventing shared test connections from being closed too early while still closing runtime-owned connections.
+- Migration CLI paths now close SQLite/Postgres stores deterministically after status/apply operations.
+- Warning-sensitive test runs no longer emit unclosed sqlite database ResourceWarnings.
+
+## 0.2.0-alpha
+
+### Added
+
+- Python reference runtime.
+- Local SQLite WAL StateStore.
+- Local file BlobStore.
+- AgentContext, Runtime, ToolRegistry, and ToolGateway.
+- Tool Ledger for managed side effects and idempotency.
+- Event-level replay summary.
+- Evidence bundle export.
+- Evidence diff, evidence check report, and trace JSONL exporter.
+- Cost and budget records.
+- Approval request/approve/deny flow.
+- Policy YAML/JSON loader.
+- Local scheduler with heartbeat, lease recovery, cancellation, and retry policy.
+- Local worker loop.
+- Sandbox executor contract with local, disabled, bubblewrap, Docker, Kubernetes, E2B, Firecracker, and custom adapter slots.
+- Simple API: `agent`, `run`, `arun`.
+- LangGraph and MCP dependency-free adapter skeletons.
+- Postgres DDL skeleton and optional dependency boundary.
+- StateStore conformance runner.
+
+### Known Limitations
+
+- Postgres and S3/MinIO adapters are experimental and not production-hardened.
+- Distributed worker deployment is not complete.
+- OTLP collector transport is dependency-free and experimental.
+- Exact optional framework packages are not implemented.
+- Rust, TypeScript, and Go implementations are not started.
+- Production sandbox hardening requires external deployment policy.

agentledger_runtime-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of Conduct
+
+AgentLedger is an open-source engineering project. Contributors, maintainers, and users are expected to keep discussions technical, respectful, and constructive.
+
+## Expected behavior
+
+- Be respectful when reviewing designs, code, issues, and release decisions.
+- Prefer concrete evidence, reproducible examples, and clear trade-offs.
+- Assume good intent, but make risks and failure modes explicit.
+- Keep security-sensitive reports out of public issues until maintainers have reviewed them.
+- Respect the project scope: durable execution, reliability, governance, replay, and adapter contracts for AI agent runtimes.
+
+## Unacceptable behavior
+
+- Harassment, personal attacks, or discriminatory language.
+- Publishing private information, credentials, exploit details, or sensitive logs without permission.
+- Repeatedly derailing issues or pull requests away from their technical purpose.
+- Pressuring maintainers to bypass release, security, or compatibility checks.
+
+## Enforcement
+
+Maintainers may edit or remove comments, close issues, reject contributions, or restrict participation when behavior harms the project. Security concerns should be reported through `SECURITY.md`.

agentledger_runtime-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to AgentLedger
+
+AgentLedger is intentionally framework-agnostic. Contributions should preserve the runtime boundary: agent business logic runs through `AgentContext`, while durable state, tool calls, policy, audit, and replay remain runtime-managed.
+
+## Local Development
+
+```bash
+PYTHONPYCACHEPREFIX=/tmp/agentledger-pycache PYTHONPATH=src python3 -m compileall -q src tests examples
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -q
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger --root /tmp/agentledger-dev-check conformance
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger lint boundary examples src --exclude src/agentledger --no-fail
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger contract export > /tmp/agentledger-contract.json
+python3 -m json.tool /tmp/agentledger-contract.json >/dev/null
+diff -u contracts/agentledger.runtime.v0.json /tmp/agentledger-contract.json
+```
+
+## Contribution Principles
+
+- Keep core dependencies minimal; put framework integrations behind adapters.
+- Treat tool side effects as managed operations with idempotency and audit records.
+- Prefer explicit state transitions over hidden mutable state.
+- Add tests for failure paths, not only happy paths.
+- Do not make replay or shadow mode perform real external side effects.
+- Keep Python as the reference implementation, not the protocol boundary.
+- Keep Rust, TypeScript, and Go work aligned with `contracts/agentledger.runtime.v0.json`.
+
+## Required Checks
+
+Before opening a pull request, run:
+
+```bash
+PYTHONPYCACHEPREFIX=/tmp/agentledger-pycache PYTHONPATH=src python3 -m compileall -q src tests examples
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -q
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src PYTHONTRACEMALLOC=10 python3 -W default::ResourceWarning -m unittest discover -s tests -q
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger --root /tmp/agentledger-pr-check conformance >/tmp/agentledger-conformance.json
+python3 -m json.tool /tmp/agentledger-conformance.json >/dev/null
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger lint boundary examples src --exclude src/agentledger --no-fail >/tmp/agentledger-boundary-lint.json
+python3 -m json.tool /tmp/agentledger-boundary-lint.json >/dev/null
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger contract export > /tmp/agentledger-contract.json
+python3 -m json.tool /tmp/agentledger-contract.json >/dev/null
+diff -u contracts/agentledger.runtime.v0.json /tmp/agentledger-contract.json
+```
+
+The full release gate is documented in `docs/RELEASE_CHECKLIST.md`.
+
+If you change runtime events, wire objects, or invariants, update both `src/agentledger/contract.py` and `contracts/agentledger.runtime.v0.json`.
+
+If you change examples, tool catalogs, media/stream contracts, worker loops, or CLI docs, also run the relevant example smoke commands in `docs/RELEASE_CHECKLIST.md`.
+
+Do not add destructive database cleanup commands to the required check path. Adapter tests should use temporary data or explicitly configured test services only.
+
+Optional Postgres adapter changes should also run the real-service smoke test when credentials are available:
+
+```bash
+AGENTLEDGER_RUN_POSTGRES_INTEGRATION=1 AGENTLEDGER_POSTGRES_DSN=<dsn> PYTHONPATH=src python3 -m unittest tests.test_postgres_integration -v
+```
+
+Optional S3/MinIO adapter changes should also run the real-service smoke test when credentials are available:
+
+```bash
+AGENTLEDGER_RUN_S3_INTEGRATION=1 AGENTLEDGER_S3_BUCKET=<bucket> PYTHONPATH=src python3 -m unittest tests.test_s3_integration -v
+```
+
+If you change storage schema, update:
+
+```text
+src/agentledger/storage_schema.py
+migrations/sqlite/
+migrations/postgres/
+docs/STORAGE.md
+```
+
+## Compatibility Expectations
+
+Adapters and multi-language implementations should preserve:
+
+```text
+event ordering
+lease/fencing checks
+state version checks
+Tool Ledger idempotency
+approval-before-execution
+sandbox fail-closed behavior
+replay/shadow side-effect blocking
+```
+
+## Roadmap Fit
+
+Good first contribution areas:
+
+- storage adapters behind the existing store boundary
+- framework adapters for LangGraph, AutoGen, CrewAI, LlamaIndex, Semantic Kernel, OpenAI Agents SDK, and MCP
+- richer policy engines and approval workflows
+- replay/evidence bundle export
+- observability exporters
+- TypeScript worker/client targeting the runtime contract
+- Rust runtime primitive or worker experiments
+- Go infrastructure worker/client experiments

agentledger_runtime-1.0.0/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work. If You institute patent litigation against any entity alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within that NOTICE file, excluding notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort, contract, or otherwise, unless required by applicable law or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages arising as a result of this License or out of the use or inability to use the Work, even if a Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS