PyPI - agentledger-runtime - Versions diffs - 1.2.3__tar.gz → 1.2.4__tar.gz - Mend

agentledger-runtime 1.2.3tar.gz → 1.2.4tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (367) hide show

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/CHANGELOG.md RENAMED Viewed

@@ -8,6 +8,43 @@ This project follows semantic versioning for the stable runtime-core contract. O
 No unreleased changes yet.
+## 1.2.4
+### Added
+- Open-source impact documentation for AgentLedger's early-stage agent reliability and governance infrastructure positioning.
+- Maintainer notes documenting project ownership, review principles, release responsibilities, coding-agent usage, and maintenance signals.
+- Cross-language 3-minute side-effect safety demos showing crash/retry without duplicate external writes.
+- Cross-language MCP governance examples showing descriptor annotations for side effects, approval, sandbox metadata, idempotency, and audit evidence.
+- Adoption plan, public issue/discussion candidates, and a legal-agent case study template.
+### Changed
+- README first screen now leads with the tool side-effect safety problem before describing architecture.
+- MCP tool adapter now maps governance annotations such as `approval_required`, `sandbox_required`, `sandbox_executor`, and `sandbox_policy`.
+### Clarified
+- Roadmap guidance for open-source adoption, OpenAI Agents SDK/MCP examples, Codex-assisted maintainer workflows, and public usage evidence without changing runtime-core semantics.
+- 1.2.4 does not change runtime-core semantics; it is an adoption and example-focused release.
+## 1.2.3
+### Added
+- SQL query examples for runtime inspection, multi-table timelines, approvals, costs, artifacts, and large business-schema integration patterns.
+- `agentledger-langfuse` as an official optional observability adapter boundary.
+- TypeScript subpath/package, Go adapter boundary, and Rust crate/feature boundary for Langfuse-style evidence/trace payload export.
+### Changed
+- Updated adapter packaging, certification, optional-adapter conformance, and documentation entrypoints for the Langfuse adapter boundary.
+- Removed tracked local runtime state from the repository.
+### Clarified
+- Langfuse support is an adapter/export boundary, not a replacement for Langfuse or a binding to the Langfuse SDK.
 ## 1.2.2
 ### Added

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentledger-runtime
-Version: 1.2.3
+Version: 1.2.4
 Summary: Runtime reliability layer for Agent Harness stacks
 Project-URL: Homepage, https://github.com/yaogdu/AgentLedger
 Project-URL: Repository, https://github.com/yaogdu/AgentLedger
@@ -52,14 +52,16 @@ Description-Content-Type: text/markdown
 [English](README.md) | [中文](README.zh-CN.md)
 ![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
-![Version 1.2.3 stable](https://img.shields.io/badge/Version-1.2.3--stable-111827)
+![Version 1.2.4 stable](https://img.shields.io/badge/Version-1.2.4--stable-111827)
 ![License Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-0f766e)
 ![Runtime Durable](https://img.shields.io/badge/Runtime-durable%20execution-1f6feb)
 ![Storage SQLite/Postgres/MySQL](https://img.shields.io/badge/Storage-SQLite%20%7C%20Postgres%20%7C%20MySQL-b45309)
 ![Replay Evidence](https://img.shields.io/badge/Replay-evidence%20driven-7c3aed)
 ![Tool Ledger](https://img.shields.io/badge/Tools-ledger%20guarded-d97706)
-AgentLedger `1.2.3` is a runtime reliability layer for Agent Harness stacks. It does not try to teach agents how to reason or replace the surrounding harness ecosystem; it makes agent runs durable, auditable, replayable, policy-governed, and recoverable when workers crash, tools fail, or prompts change.
+Your agent called a tool. Did it happen? Can you retry safely? Can you prove it later?
+AgentLedger `1.2.4` is a runtime reliability layer for Agent Harness stacks. It does not try to teach agents how to reason or replace the surrounding harness ecosystem; it makes agent runs durable, auditable, replayable, policy-governed, and recoverable when workers crash, tools fail, or prompts change.
 Most agent frameworks focus on planning, reasoning, and workflow logic. AgentLedger sits underneath or beside LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, LlamaIndex, Semantic Kernel, or custom agents to provide runtime guarantees around state, tools, evidence, replay, and recovery.
@@ -76,6 +78,9 @@ Python remains the reference implementation, and Go, TypeScript, and Rust now ha
 | Find runnable examples | [examples/README.md](examples/README.md), [go/examples/README.md](go/examples/README.md), [typescript/examples/README.md](typescript/examples/README.md), [rust/examples/README.md](rust/examples/README.md) |
 | Query runtime tables | [docs/QUERY_EXAMPLES.md](docs/QUERY_EXAMPLES.md) |
 | Understand Harness stack composition | [docs/HARNESS_STACK.md](docs/HARNESS_STACK.md) |
+| Understand open-source impact | [docs/OPEN_SOURCE_IMPACT.md](docs/OPEN_SOURCE_IMPACT.md) |
+| Understand maintainer responsibilities | [docs/MAINTAINER_NOTES.md](docs/MAINTAINER_NOTES.md) |
+| Plan adoption work | [docs/ADOPTION.md](docs/ADOPTION.md) |
 | Understand what is equal across languages | [docs/LANGUAGE_IMPLEMENTATION_COMPARISON.md](docs/LANGUAGE_IMPLEMENTATION_COMPARISON.md) |
 | Install optional adapter packages | [docs/ADAPTER_PACKAGING.md](docs/ADAPTER_PACKAGING.md) |
 | Use Go correctly | [go/README.md](go/README.md#install) |
@@ -164,10 +169,12 @@ The intended production shape is therefore not `AgentLedger instead of LangGraph
 ## Examples
-The repository includes small quickstarts plus a richer multi-language Travel Assistant demo that shows the same runtime ideas across Python, Go, Rust, and TypeScript.
+The repository includes cross-language 3-minute side-effect safety demos, MCP governance demos, small quickstarts, and a richer multi-language Travel Assistant demo that shows the same runtime ideas across Python, Go, Rust, and TypeScript.
-| Language | Demo | Run |
+| Goal | Demo | Run |
 | --- | --- | --- |
+| 3-minute side-effect safety | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/three_minute_demo/demo.py`; `cd go && go run ./examples/three_minute_demo`; `cd rust && cargo run --example three_minute_demo`; `cd typescript && node examples/three_minute_demo/three_minute_demo.js` |
+| MCP tool governance | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/mcp_governance/demo.py`; `cd go && go run ./examples/mcp_governance`; `cd rust && cargo run --example mcp_governance`; `cd typescript && node examples/mcp_governance/mcp_governance.js` |
 | Python | `examples/travel_assistant/demo.py` | `python3 examples/travel_assistant/demo.py` |
 | Go | `go/examples/travel_assistant/main.go` | `cd go && go run examples/travel_assistant/main.go` |
 | Rust | `rust/examples/travel_assistant.rs` | `cd rust && cargo run --example travel_assistant` |
@@ -322,7 +329,7 @@ AgentLedger is also not a new LLM SDK, not a workflow engine, not a general obse
 ## Current maturity
-AgentLedger 1.2.3 is a stable runtime-core release with Python as the reference implementation and Go, TypeScript, and Rust covered by shared runtime-core parity gates. It is suitable for local use, framework adapter integration, reliability semantics validation, and production pilot preparation with explicit adapter boundaries.
+AgentLedger 1.2.4 is a stable runtime-core release with Python as the reference implementation and Go, TypeScript, and Rust covered by shared runtime-core parity gates. It is suitable for local use, framework adapter integration, reliability semantics validation, and production pilot preparation with explicit adapter boundaries.
 The runtime-core contract is stable; optional production adapters and external infrastructure hardening remain separately tracked. See [docs/MATURITY_MODEL.md](docs/MATURITY_MODEL.md), [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md), and [docs/ROADMAP.md](docs/ROADMAP.md).

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/README.md RENAMED Viewed

@@ -3,14 +3,16 @@
 [English](README.md) | [中文](README.zh-CN.md)
 ![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
-![Version 1.2.3 stable](https://img.shields.io/badge/Version-1.2.3--stable-111827)
+![Version 1.2.4 stable](https://img.shields.io/badge/Version-1.2.4--stable-111827)
 ![License Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-0f766e)
 ![Runtime Durable](https://img.shields.io/badge/Runtime-durable%20execution-1f6feb)
 ![Storage SQLite/Postgres/MySQL](https://img.shields.io/badge/Storage-SQLite%20%7C%20Postgres%20%7C%20MySQL-b45309)
 ![Replay Evidence](https://img.shields.io/badge/Replay-evidence%20driven-7c3aed)
 ![Tool Ledger](https://img.shields.io/badge/Tools-ledger%20guarded-d97706)
-AgentLedger `1.2.3` is a runtime reliability layer for Agent Harness stacks. It does not try to teach agents how to reason or replace the surrounding harness ecosystem; it makes agent runs durable, auditable, replayable, policy-governed, and recoverable when workers crash, tools fail, or prompts change.
+Your agent called a tool. Did it happen? Can you retry safely? Can you prove it later?
+AgentLedger `1.2.4` is a runtime reliability layer for Agent Harness stacks. It does not try to teach agents how to reason or replace the surrounding harness ecosystem; it makes agent runs durable, auditable, replayable, policy-governed, and recoverable when workers crash, tools fail, or prompts change.
 Most agent frameworks focus on planning, reasoning, and workflow logic. AgentLedger sits underneath or beside LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, LlamaIndex, Semantic Kernel, or custom agents to provide runtime guarantees around state, tools, evidence, replay, and recovery.
@@ -27,6 +29,9 @@ Python remains the reference implementation, and Go, TypeScript, and Rust now ha
 | Find runnable examples | [examples/README.md](examples/README.md), [go/examples/README.md](go/examples/README.md), [typescript/examples/README.md](typescript/examples/README.md), [rust/examples/README.md](rust/examples/README.md) |
 | Query runtime tables | [docs/QUERY_EXAMPLES.md](docs/QUERY_EXAMPLES.md) |
 | Understand Harness stack composition | [docs/HARNESS_STACK.md](docs/HARNESS_STACK.md) |
+| Understand open-source impact | [docs/OPEN_SOURCE_IMPACT.md](docs/OPEN_SOURCE_IMPACT.md) |
+| Understand maintainer responsibilities | [docs/MAINTAINER_NOTES.md](docs/MAINTAINER_NOTES.md) |
+| Plan adoption work | [docs/ADOPTION.md](docs/ADOPTION.md) |
 | Understand what is equal across languages | [docs/LANGUAGE_IMPLEMENTATION_COMPARISON.md](docs/LANGUAGE_IMPLEMENTATION_COMPARISON.md) |
 | Install optional adapter packages | [docs/ADAPTER_PACKAGING.md](docs/ADAPTER_PACKAGING.md) |
 | Use Go correctly | [go/README.md](go/README.md#install) |
@@ -115,10 +120,12 @@ The intended production shape is therefore not `AgentLedger instead of LangGraph
 ## Examples
-The repository includes small quickstarts plus a richer multi-language Travel Assistant demo that shows the same runtime ideas across Python, Go, Rust, and TypeScript.
+The repository includes cross-language 3-minute side-effect safety demos, MCP governance demos, small quickstarts, and a richer multi-language Travel Assistant demo that shows the same runtime ideas across Python, Go, Rust, and TypeScript.
-| Language | Demo | Run |
+| Goal | Demo | Run |
 | --- | --- | --- |
+| 3-minute side-effect safety | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/three_minute_demo/demo.py`; `cd go && go run ./examples/three_minute_demo`; `cd rust && cargo run --example three_minute_demo`; `cd typescript && node examples/three_minute_demo/three_minute_demo.js` |
+| MCP tool governance | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/mcp_governance/demo.py`; `cd go && go run ./examples/mcp_governance`; `cd rust && cargo run --example mcp_governance`; `cd typescript && node examples/mcp_governance/mcp_governance.js` |
 | Python | `examples/travel_assistant/demo.py` | `python3 examples/travel_assistant/demo.py` |
 | Go | `go/examples/travel_assistant/main.go` | `cd go && go run examples/travel_assistant/main.go` |
 | Rust | `rust/examples/travel_assistant.rs` | `cd rust && cargo run --example travel_assistant` |
@@ -273,7 +280,7 @@ AgentLedger is also not a new LLM SDK, not a workflow engine, not a general obse
 ## Current maturity
-AgentLedger 1.2.3 is a stable runtime-core release with Python as the reference implementation and Go, TypeScript, and Rust covered by shared runtime-core parity gates. It is suitable for local use, framework adapter integration, reliability semantics validation, and production pilot preparation with explicit adapter boundaries.
+AgentLedger 1.2.4 is a stable runtime-core release with Python as the reference implementation and Go, TypeScript, and Rust covered by shared runtime-core parity gates. It is suitable for local use, framework adapter integration, reliability semantics validation, and production pilot preparation with explicit adapter boundaries.
 The runtime-core contract is stable; optional production adapters and external infrastructure hardening remain separately tracked. See [docs/MATURITY_MODEL.md](docs/MATURITY_MODEL.md), [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md), and [docs/ROADMAP.md](docs/ROADMAP.md).

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/README.zh-CN.md RENAMED Viewed

@@ -3,14 +3,16 @@
 [English](README.md) | [中文](README.zh-CN.md)
 ![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
-![Version 1.2.3 stable](https://img.shields.io/badge/Version-1.2.3--stable-111827)
+![Version 1.2.4 stable](https://img.shields.io/badge/Version-1.2.4--stable-111827)
 ![License Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-0f766e)
 ![Runtime Durable](https://img.shields.io/badge/Runtime-durable%20execution-1f6feb)
 ![Storage SQLite/Postgres/MySQL](https://img.shields.io/badge/Storage-SQLite%20%7C%20Postgres%20%7C%20MySQL-b45309)
 ![Replay Evidence](https://img.shields.io/badge/Replay-evidence%20driven-7c3aed)
 ![Tool Ledger](https://img.shields.io/badge/Tools-ledger%20guarded-d97706)
-AgentLedger `1.2.3` 是面向 Agent Harness stack 的 runtime reliability layer。它不负责让 Agent 更会“思考”，也不替代完整 Harness 生态；它负责让 Agent run 在 worker 崩溃、工具失败、prompt 变更和长任务恢复时，仍然具备持久化、可审计、可重放、可治理和可恢复能力。
+你的 Agent 调用了一个工具。它真的执行了吗？可以安全重试吗？之后能证明发生过什么吗？
+AgentLedger `1.2.4` 是面向 Agent Harness stack 的 runtime reliability layer。它不负责让 Agent 更会“思考”，也不替代完整 Harness 生态；它负责让 Agent run 在 worker 崩溃、工具失败、prompt 变更和长任务恢复时，仍然具备持久化、可审计、可重放、可治理和可恢复能力。
 大多数 Agent 框架关注 planning、reasoning 和 workflow logic。AgentLedger 放在 LangChain、LangGraph、CrewAI、AutoGen、OpenAI Agents SDK、LlamaIndex、Semantic Kernel 或自定义 Agent 的下方或旁边，提供 state、tool、evidence、replay、recovery 相关的 runtime guarantees。
@@ -27,6 +29,9 @@ Python 仍然是 reference implementation；Go、TypeScript、Rust 已有 native
 | 找可运行示例 | [examples/README.md](examples/README.md)、[go/examples/README.md](go/examples/README.md)、[typescript/examples/README.md](typescript/examples/README.md)、[rust/examples/README.md](rust/examples/README.md) |
 | 查询 runtime 表 | [docs/zh/QUERY_EXAMPLES.md](docs/zh/QUERY_EXAMPLES.md) |
 | 理解 Harness stack 组合方式 | [docs/zh/HARNESS_STACK.md](docs/zh/HARNESS_STACK.md) |
+| 理解开源生态价值 | [docs/zh/OPEN_SOURCE_IMPACT.md](docs/zh/OPEN_SOURCE_IMPACT.md) |
+| 理解维护者职责 | [docs/zh/MAINTAINER_NOTES.md](docs/zh/MAINTAINER_NOTES.md) |
+| 规划 adoption 工作 | [docs/zh/ADOPTION.md](docs/zh/ADOPTION.md) |
 | 理解四语言哪些对齐、哪些不对齐 | [docs/zh/LANGUAGE_IMPLEMENTATION_COMPARISON.md](docs/zh/LANGUAGE_IMPLEMENTATION_COMPARISON.md) |
 | 安装 optional adapter packages | [docs/zh/ADAPTER_PACKAGING.md](docs/zh/ADAPTER_PACKAGING.md) |
 | 正确使用 Go | [go/README.md](go/README.md#install) |
@@ -116,10 +121,12 @@ AgentLedger 本身不是完整 Agent Harness。它的设计目标是和 Harness
 ## 示例
-仓库里既有最小 quickstart，也有一个更完整的多语言 Travel Assistant demo，用来展示 Python、Go、Rust、TypeScript 下相同的 runtime 思路。
+仓库里包含四语言 3-minute side-effect safety demo、MCP governance demo、最小 quickstart，以及一个更完整的多语言 Travel Assistant demo，用来展示 Python、Go、Rust、TypeScript 下相同的 runtime 思路。
-| 语言 | Demo | 运行方式 |
+| 目标 | Demo | 运行方式 |
 | --- | --- | --- |
+| 3 分钟副作用安全 demo | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/three_minute_demo/demo.py`; `cd go && go run ./examples/three_minute_demo`; `cd rust && cargo run --example three_minute_demo`; `cd typescript && node examples/three_minute_demo/three_minute_demo.js` |
+| MCP tool governance | Python / Go / Rust / TypeScript | `PYTHONPATH=src python3 examples/mcp_governance/demo.py`; `cd go && go run ./examples/mcp_governance`; `cd rust && cargo run --example mcp_governance`; `cd typescript && node examples/mcp_governance/mcp_governance.js` |
 | Python | `examples/travel_assistant/demo.py` | `python3 examples/travel_assistant/demo.py` |
 | Go | `go/examples/travel_assistant/main.go` | `cd go && go run examples/travel_assistant/main.go` |
 | Rust | `rust/examples/travel_assistant.rs` | `cd rust && cargo run --example travel_assistant` |
@@ -274,7 +281,7 @@ AgentLedger 也不是新的 LLM SDK，不是 workflow engine，不是通用 obse
 ## 当前成熟度
-AgentLedger 1.2.0 是 stable runtime-core release，Python 是 reference implementation，Go、TypeScript、Rust 已由共享 runtime-core parity gate 覆盖；适合本地使用、framework adapter integration、reliability semantics 验证，以及在明确 adapter 边界下做 production pilot 准备。
+AgentLedger 1.2.4 是 stable runtime-core release，Python 是 reference implementation，Go、TypeScript、Rust 已由共享 runtime-core parity gate 覆盖；适合本地使用、framework adapter integration、reliability semantics 验证，以及在明确 adapter 边界下做 production pilot 准备。
 runtime-core contract 已稳定；optional production adapter 和外部基础设施加固仍按独立阶段推进。详见 [docs/MATURITY_MODEL.md](docs/MATURITY_MODEL.md)、[docs/zh/IMPLEMENTATION_STATUS.md](docs/zh/IMPLEMENTATION_STATUS.md) 和 [docs/zh/ROADMAP.md](docs/zh/ROADMAP.md)。

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/ADAPTER_CERTIFICATION.md RENAMED Viewed

@@ -212,10 +212,10 @@ This does not make an adapter production-ready by itself. It gives users a concr
 AgentLedger can generate a machine-readable starting bundle for official adapter profiles:
 ```bash
-PYTHONPATH=src python3 -m agentledger adapter certify --kind postgres --adapter-version 1.2.3
-PYTHONPATH=src python3 -m agentledger adapter certify --kind mysql --adapter-version 1.2.3 --out ./mysql-certification.json
-PYTHONPATH=src python3 -m agentledger adapter certify --kind s3 --adapter-version 1.2.3 --out ./s3-certification.json
-PYTHONPATH=src python3 -m agentledger adapter certify --kind langgraph --adapter-version 1.2.3 --package-name agentledger-langgraph
+PYTHONPATH=src python3 -m agentledger adapter certify --kind postgres --adapter-version 1.2.4
+PYTHONPATH=src python3 -m agentledger adapter certify --kind mysql --adapter-version 1.2.4 --out ./mysql-certification.json
+PYTHONPATH=src python3 -m agentledger adapter certify --kind s3 --adapter-version 1.2.4 --out ./s3-certification.json
+PYTHONPATH=src python3 -m agentledger adapter certify --kind langgraph --adapter-version 1.2.4 --package-name agentledger-langgraph
 ```
 Supported built-in profiles:

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/ADAPTER_PACKAGING.md RENAMED Viewed

@@ -223,8 +223,8 @@ The `1.2.x` packaging release is expected to pass:
 ```bash
 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -q
-PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger adapter certify --kind postgres --adapter-version 1.2.3
-PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger adapter certify --kind mysql --adapter-version 1.2.3
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger adapter certify --kind postgres --adapter-version 1.2.4
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger adapter certify --kind mysql --adapter-version 1.2.4
 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 scripts/check_adapter_packages.py
 go test ./...
 cd typescript && npm test

agentledger_runtime-1.2.4/docs/ADOPTION.md ADDED Viewed

@@ -0,0 +1,58 @@
+# Adoption Plan
+This document tracks near-term work that makes AgentLedger easier to understand, try, discuss, and validate. It does not change runtime-core scope.
+## Why This Track Exists
+AgentLedger already has substantial runtime-core depth. The next adoption bottleneck is not another large feature; it is helping a new user answer three questions quickly:
+```text
+What problem does this solve?
+Can I see it in three minutes?
+Can I verify the reliability claim myself?
+```
+## Current Adoption Priorities
+| Priority | Item | Acceptance criteria |
+|---|---|---|
+| P0 | 3-minute demo | A user can run the Python, Go, TypeScript, or Rust 3-minute demo and see one external side effect, one Tool Ledger entry, safe retry, and replay-safe evidence. |
+| P0 | README first-screen pain point | The first screen explains the tool side-effect problem before listing architecture. |
+| P1 | MCP governance example | Dependency-free MCP-style tools demonstrate schema, approval, sandbox metadata, idempotency, and audit evidence across Python, Go, TypeScript, and Rust. |
+| P1 | Public issue/discussion list | The next adoption tasks are easy to open as GitHub issues or discussions. |
+| P1 | Case study template | A real integration can be documented without exposing private data. |
+## Suggested Public Issues
+These can be opened as GitHub issues when the project is ready for public tracking.
+| Title | Type | Why it matters |
+|---|---|---|
+| Build a cross-language 3-minute Tool Ledger demo | example | Shows the core value in a few minutes across Python, Go, TypeScript, and Rust. |
+| Add OpenAI Agents SDK approval/replay example | example | Connects AgentLedger to a major agent SDK boundary without claiming official endorsement. |
+| Add MCP tool governance example | example | Shows how MCP-style tools should pass through policy, approval, sandbox, idempotency, and evidence. |
+| Prototype AgentLedger Inspector | product | Makes run timelines, Tool Ledger, approvals, replay, and failures visible. |
+| Add Temporal bridge example | integration | Clarifies Temporal owns workflow lifecycle while AgentLedger owns node-internal reliability. |
+| Add tool-injection risk scanner | security | Detects risky tool schemas, missing approval/sandbox, and runtime-boundary bypass patterns. |
+| Publish legal-agent case study | case study | Shows a realistic audit/evidence use case without private data. |
+## Case Study Rules
+Case studies should be useful but conservative:
+- remove private data, customer data, secrets, and internal implementation details
+- describe the runtime problem before describing AgentLedger
+- show the AgentLedger integration boundary
+- include concrete evidence artifacts only when safe
+- avoid claiming production hardening unless real operational evidence exists
+## Good Adoption Evidence
+- runnable examples
+- short terminal recordings or GIFs
+- public issues and discussions
+- package downloads
+- real integration notes
+- external demos or blog posts
+- adapter conformance reports
+- real-service hardening reports

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/COMPLETE_CORE_PARITY_CHECKLIST.md RENAMED Viewed

@@ -55,8 +55,8 @@ Excluded or not applicable:
 | CLI baseline | `--help`, `doctor`, `version`, `quickstart`, `conformance`, `contract validate`, `contract export` | `agentledger` CLI | `agentledger-go` | `agentledger-ts` | `agentledger-rust` | `scripts/check_complete_core_parity.py` | done |
 | Quickstart docs | Language quickstart and adapter quickstart | README + docs | `go/README.md` | `typescript/README.md` | `rust/README.md` | docs link check | done |
 | Examples | Runnable examples for core runtime and adapter API | Python examples | `go/examples/quickstart/main.go` | `typescript/examples/quickstart/quickstart.js` | `rust/examples/quickstart.rs` | `scripts/check_complete_core_parity.py` | done |
-| Package metadata | Installable package metadata in the current release train | PyPI metadata `1.2.3` | `go.mod` tag `go/v1.2.3` | npm package `1.2.3` | `Cargo.toml` `1.2.3` | `scripts/check_complete_core_parity.py` version check | done |
-| Package install smoke | Install/import/run from published or built package | PyPI `agentledger-runtime==1.2.3` release smoke after publish | `go/v1.2.3` clean external `go get` smoke after tag | npm `agentledger-runtime@1.2.3` release smoke after publish | crates.io `agentledger-runtime==1.2.3` release smoke after publish | publish logs + `scripts/check_complete_core_parity.py` dry-run gates | release-gated |
+| Package metadata | Installable package metadata in the current release train | PyPI metadata `1.2.4` | `go.mod` tag `go/v1.2.4` | npm package `1.2.4` | `Cargo.toml` `1.2.4` | `scripts/check_complete_core_parity.py` version check | done |
+| Package install smoke | Install/import/run from published or built package | PyPI `agentledger-runtime==1.2.4` release smoke after publish | `go/v1.2.4` clean external `go get` smoke after tag | npm `agentledger-runtime@1.2.4` release smoke after publish | crates.io `agentledger-runtime==1.2.4` release smoke after publish | publish logs + `scripts/check_complete_core_parity.py` dry-run gates | release-gated |
 | Release docs | Changelog, release checklist, status docs reflect exact parity boundary | docs | docs | docs | docs | docs link check | done |
 | Comparison docs | Honest overlap with LangChain/LangGraph/LangSmith/Langfuse/etc. | docs | docs | docs | docs | docs link check | done |
@@ -67,7 +67,7 @@ The strict core parity gate now covers the previously weak areas:
 1. CLI baseline is automatically checked for all four language CLIs.
 2. Go, TypeScript, and Rust have runnable quickstart example files.
 3. TypeScript and Rust package surfaces have package dry-run checks (`npm pack --dry-run`, `cargo package --allow-dirty --no-verify`) and post-publish install smokes are required for release.
-4. Package versions are checked across Python, TypeScript, and Rust; the current release train is aligned at `1.2.3`.
+4. Package versions are checked across Python, TypeScript, and Rust; the current release train is aligned at `1.2.4`.
 5. Go external module consumption is tag/release dependent; each release should repeat the clean external `go get` smoke after pushing the `go/vX.Y.Z` tag.
 6. Real service-backed hardening remains out of scope for core parity and stays documented as optional follow-up work.

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/GETTING_STARTED.md RENAMED Viewed

@@ -9,7 +9,7 @@ This is the shortest path from install to a working AgentLedger run. If you are
 | Language | Install / use | Quickstart | Examples | Package / command |
 |---|---|---|---|---|
 | Python | `pipx install agentledger-runtime` or `pip install agentledger-runtime` | `agentledger quickstart` | `../examples/README.md` | PyPI package `agentledger-runtime`, CLI `agentledger` |
-| Go | `go get github.com/yaogdu/AgentLedger/go@v1.2.3` inside a Go module | `cd go && go run ./examples/quickstart` from this repo | `../go/examples/README.md` | Go module `github.com/yaogdu/AgentLedger/go`, CLI package `.../go/cmd/agentledger-go` |
+| Go | `go get github.com/yaogdu/AgentLedger/go@v1.2.4` inside a Go module | `cd go && go run ./examples/quickstart` from this repo | `../go/examples/README.md` | Go module `github.com/yaogdu/AgentLedger/go`, CLI package `.../go/cmd/agentledger-go` |
 | TypeScript | `npm install agentledger-runtime` | `node typescript/examples/quickstart/quickstart.js` | `../typescript/examples/README.md` | npm package `agentledger-runtime`, CLI `agentledger-ts` |
 | Rust | crates.io package: `agentledger-runtime` | `cargo add agentledger-runtime` 或 `cd rust && cargo run --example quickstart` | `../rust/examples/README.md` | crate `agentledger-runtime`, binary `agentledger-rust` |
@@ -36,17 +36,17 @@ Use the library inside a Go module:
 ```bash
 go mod init your-module-name  # only if your project does not already have go.mod
-go get github.com/yaogdu/AgentLedger/go@v1.2.3
+go get github.com/yaogdu/AgentLedger/go@v1.2.4
 ```
 Install the optional CLI:
 ```bash
-go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.2.3
+go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.2.4
 agentledger-go --help
 ```
-Important: `go get` must run inside a Go module. `go install github.com/yaogdu/AgentLedger/go@v1.2.3` is not valid because that path is a library, not `package main`. Use `/cmd/agentledger-go` for the CLI.
+Important: `go get` must run inside a Go module. `go install github.com/yaogdu/AgentLedger/go@v1.2.4` is not valid because that path is a library, not `package main`. Use `/cmd/agentledger-go` for the CLI.
 ### TypeScript
@@ -88,12 +88,14 @@ The crate is published as `agentledger-runtime`; the library crate is imported a
 | Goal | Example |
 |---|---|
+| Understand the core value in 3 minutes | `../examples/three_minute_demo/README.md`; Go `../go/examples/three_minute_demo`; TypeScript `../typescript/examples/three_minute_demo`; Rust `../rust/examples/three_minute_demo.rs` |
 | Smallest Python run | `../examples/hello_world/hello.py` |
 | Idempotent side effects | `../examples/side_effect_idempotency/README.md` |
 | Retry transient errors | `../examples/transient_retry/README.md` |
 | LangGraph integration | `../examples/langgraph/basic_graph.py` |
 | LangChain integration | `../examples/langchain/basic_runnable.py` |
 | MCP tool/context | `../examples/mcp_tool/basic_tool.py`, `../examples/mcp_context/basic_context_server.py` |
+| MCP governance | `../examples/mcp_governance/README.md`; Go `../go/examples/mcp_governance`; TypeScript `../typescript/examples/mcp_governance`; Rust `../rust/examples/mcp_governance.rs` |
 | Sandbox command tool | `../examples/sandbox/command_tool.py` |
 | Media/stream refs | `../examples/media_stream/basic_media_stream.py` |
 | Go quickstart | `../go/examples/quickstart/main.go` |

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/IMPLEMENTATION_STATUS.md RENAMED Viewed

@@ -1,12 +1,12 @@
 # Implementation Status
-Updated: 2026-05-27
+Updated: 2026-06-05
 This document tracks what is implemented in runtime-core, what remains planned for optional adapters, and what should stay outside runtime-core.
 ## Current Baseline
-AgentLedger 1.2.3 is a stable runtime-core line with Python as the reference implementation and Go/TypeScript/Rust covered by shared runtime-core parity gates. The 1.2.x line adds adapter packaging boundaries across the supported language ecosystems and now includes the official MySQL storage adapter boundary plus a dependency-free Langfuse export adapter boundary while keeping selected preview/experimental concrete adapter paths explicit. It is suitable for:
+AgentLedger 1.2.4 is a stable runtime-core line with Python as the reference implementation and Go/TypeScript/Rust covered by shared runtime-core parity gates. The 1.2.x line adds adapter packaging boundaries across the supported language ecosystems and now includes the official MySQL storage adapter boundary plus a dependency-free Langfuse export adapter boundary while keeping selected preview/experimental concrete adapter paths explicit. It is suitable for:
 - local use
 - runtime design review
@@ -15,7 +15,7 @@ AgentLedger 1.2.3 is a stable runtime-core line with Python as the reference imp
 - reliability semantics validation
 - production pilot preparation with explicit adapter boundaries
-Release-scope note: 1.2.3 is a small documentation and observability-adapter release. It adds SQL query examples and `agentledger-langfuse` package boundaries without changing runtime-core semantics. MySQL remains the 1.2.2 storage adapter boundary; real-service production claims still require external validation.
+Release-scope note: 1.2.4 is an adoption and example-focused release. It adds cross-language 3-minute side-effect safety demos, cross-language MCP governance examples, adoption documentation, public issue/discussion candidates, and legal-agent case-study templates without changing runtime-core semantics. MySQL remains the 1.2.2 storage adapter boundary and Langfuse remains the 1.2.3 observability adapter boundary; real-service production claims still require external validation.
 The runtime-core contract is stable. Optional production adapters, external infrastructure hardening, and full eval systems remain outside the stable core boundary; non-Python runtime-core baselines are verified by the shared parity gates.

{agentledger_runtime-1.2.3 → agentledger_runtime-1.2.4}/docs/LANGUAGE_QUICKSTART.md RENAMED Viewed

@@ -2,7 +2,7 @@
 [English](LANGUAGE_QUICKSTART.md) | [中文](zh/LANGUAGE_QUICKSTART.md)
-AgentLedger 1.2.3 has one Python reference runtime and native preview runtime-core baselines for Go, TypeScript, and Rust. The shared promise is semantic parity for runtime-core: durable runs, leases, Tool Ledger, evidence, replay, policy/approval/sandbox boundaries, cost/failure attribution, conformance, and official optional adapter contracts.
+AgentLedger 1.2.4 has one Python reference runtime and native preview runtime-core baselines for Go, TypeScript, and Rust. The shared promise is semantic parity for runtime-core: durable runs, leases, Tool Ledger, evidence, replay, policy/approval/sandbox boundaries, cost/failure attribution, conformance, and official optional adapter contracts.
 The non-Python packages are native runtime packages, not thin clients: each runs a native local runtime loop and reports the shared conformance checks.
@@ -66,13 +66,13 @@ Use the released Go module from a Go project:
 ```bash
 go mod init your-module-name  # only if your project does not have go.mod yet
-go get github.com/yaogdu/AgentLedger/go@v1.2.3
+go get github.com/yaogdu/AgentLedger/go@v1.2.4
 ```
 Install the optional CLI command:
 ```bash
-go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.2.3
+go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.2.4
 agentledger-go --help
 agentledger-go doctor
 agentledger-go quickstart
@@ -86,7 +86,7 @@ go test . ./cmd/agentledger-go
 go run ./cmd/agentledger-go conformance
 ```
-Note: `go get` must run inside a Go module. `go install github.com/yaogdu/AgentLedger/go@v1.2.3` fails because the library package is not a `package main`; use `/cmd/agentledger-go` for the CLI.
+Note: `go get` must run inside a Go module. `go install github.com/yaogdu/AgentLedger/go@v1.2.4` fails because the library package is not a `package main`; use `/cmd/agentledger-go` for the CLI.
 Minimal runtime:
@@ -267,7 +267,7 @@ python3.11 scripts/audit_python_parity.py > /tmp/agentledger-python-parity-audit
 python3.11 scripts/check_language_parity.py --json-report /tmp/agentledger-language-parity.json
 ```
-Expected for 1.2.3:
+Expected for 1.2.4:
 ```text
 gap_count: 0
@@ -277,5 +277,5 @@ AgentLedger language parity checks passed
 ## What Not To Assume
 - Go/TypeScript/Rust are package surfaces, even though runtime-core semantics are conformance-aligned.
-- Official adapters in 1.2.3 use injected clients and dry-run manifests; real cloud SDKs and live service hardening are optional follow-up gates.
+- Official adapters in 1.2.4 use injected clients and dry-run manifests; real cloud SDKs and live service hardening are optional follow-up gates.
 - AgentLedger does not replace LangGraph, LangChain, LangSmith, Langfuse, Temporal, Ray, Kubernetes, vector DBs, or eval platforms. It provides the runtime safety/evidence layer those systems can integrate with.

agentledger_runtime-1.2.4/docs/MAINTAINER_NOTES.md ADDED Viewed

@@ -0,0 +1,88 @@
+# Maintainer Notes
+This document explains how AgentLedger is maintained and what kinds of work belong in the project. It is written for contributors, reviewers, and open-source program reviewers who need to understand the maintenance surface.
+## Maintainer Role
+The project owner and primary maintainer is responsible for:
+- runtime architecture and scope decisions
+- runtime-core contract design and compatibility
+- roadmap planning and release management
+- implementation of core reliability features
+- review of issues, pull requests, and adapter proposals
+- documentation, examples, and migration notes
+- conformance fixtures and cross-language parity gates
+- adapter certification boundaries and maturity labels
+- security posture around tools, approvals, sandbox routing, and evidence handling
+## Maintenance Principles
+AgentLedger should remain a runtime reliability layer, not a catch-all agent platform.
+- Keep runtime-core small, explicit, and dependency-light.
+- Put framework, storage, observability, sandbox, and provider integrations behind adapters.
+- Prefer contracts and conformance fixtures over undocumented behavior.
+- Treat tool side effects as auditable runtime-managed operations.
+- Record evidence for failure paths, not only successful runs.
+- Keep replay and shadow execution side-effect safe.
+- Mark maturity honestly: stable, preview, experimental, external-required, or out-of-scope.
+- Do not claim production hardening for an adapter until real-service validation exists.
+## Active Maintenance Areas
+Current maintenance work is grouped around these tracks:
+| Track | Maintainer work |
+| --- | --- |
+| Runtime contract | keep `contracts/agentledger.runtime.v1.json`, runtime events, wire objects, and invariants stable |
+| Reliability semantics | maintain leases, fencing, cancellation, checkpoint/resume, replay, shadow, and failure attribution behavior |
+| Tool governance | maintain Tool Ledger, policy decisions, approval gates, sandbox routing, idempotency, and audit evidence |
+| Storage and evidence | maintain StateStore, BlobStore, migrations, evidence bundles, static debug export, and query documentation |
+| Adapter boundaries | keep optional adapters installable without adding heavy dependencies to core |
+| Language parity | keep Python reference behavior aligned with Go, TypeScript, and Rust conformance gates |
+| Documentation | keep usage, architecture, maturity, comparison, release, and roadmap docs accurate |
+| Release quality | run release checks, package checks, language parity checks, and package publishing verification |
+## Review Checklist
+Maintainers should ask these questions during review:
+- Does this change preserve the runtime boundary?
+- Does it add hidden state or bypass runtime-managed tool calls?
+- Does it change event ordering, state versioning, or replay behavior?
+- Does it introduce a dependency that belongs in an adapter instead of runtime-core?
+- Does it handle cancellation, retry, timeout, and unknown side-effect status?
+- Does it record enough evidence for debugging and audit?
+- Does it update conformance fixtures when semantics change?
+- Does it update docs when public behavior changes?
+## Use Of Coding Agents
+Coding agents can help maintain AgentLedger, but generated changes still need normal engineering review. Useful tasks include:
+- issue triage and reproduction notes
+- adapter skeletons and conformance fixture updates
+- documentation consistency checks
+- changelog and release checklist preparation
+- regression test generation for failure paths
+- cross-language parity audits
+- examples that show approval, replay, evidence export, and sandbox behavior
+Coding agents should not be used to bypass review for security-sensitive changes, release signing, secrets, package publishing credentials, or destructive data operations.
+## Current Open Source Status
+AgentLedger is early-stage but actively maintained. It should be described as infrastructure with a stable runtime-core contract and evolving optional adapters, not as a mature hosted product or a widely deployed platform.
+The strongest public maintenance signals are:
+- versioned releases and changelog entries
+- formal runtime and adapter documentation
+- multiple language implementations
+- conformance checks across Python, Go, TypeScript, and Rust
+- examples and query/debugging documentation
+- explicit maturity and roadmap documents
+Future maintenance should strengthen real-world evidence: user examples, issues, discussions, integration guides, adapter hardening reports, and external service validation.

agentledger_runtime-1.2.4/docs/OPEN_SOURCE_IMPACT.md ADDED Viewed

@@ -0,0 +1,80 @@
+# Open Source Impact
+AgentLedger is an early-stage open-source infrastructure project for production AI agent reliability and governance. It is not an agent framework, a hosted platform, or a replacement for LangGraph, Temporal, Langfuse, MCP, or model providers. Its value is the runtime boundary those systems can share: durable state, governed tool use, evidence, replay, policy checks, sandbox routing, and cost/failure attribution.
+## Ecosystem Problem
+Most agent projects can demonstrate a successful happy path before they can operate safely in production. The harder problems appear after the first demo:
+- workers crash after a model call but before the next state commit
+- tools timeout after they may already have changed an external system
+- retries duplicate emails, tickets, database writes, or infrastructure actions
+- prompts, models, and tool schemas change without a reproducible execution record
+- reviewers cannot tell which state, tool result, policy decision, or approval caused an outcome
+- teams add ad hoc logs and retries instead of a shared reliability contract
+These are infrastructure problems, not prompt-engineering problems. AgentLedger focuses on the execution layer where state transitions, tool side effects, approvals, evidence, and replay have to be enforced consistently.
+## What AgentLedger Adds
+AgentLedger provides a runtime reliability layer that can sit beside or underneath agent frameworks and orchestration systems.
+| Capability | Ecosystem value |
+| --- | --- |
+| Durable execution records | Agent runs can be resumed, inspected, and replayed from committed runtime events instead of in-memory state. |
+| Tool Ledger | Tool side effects receive idempotency keys, causal request records, status tracking, and audit evidence. |
+| Policy and approval gates | High-risk tools can require explicit permission, human approval, or sandbox routing before execution. |
+| Evidence bundles | Debugging, review, compliance, and regression checks can consume one portable record of state, tool results, artifacts, costs, and failures. |
+| Replay and shadow semantics | Historical runs can be replayed without repeating external side effects, and new logic can be compared against recorded evidence. |
+| Adapter contracts | Frameworks, storage backends, observability sinks, MCP-style tool systems, and sandbox executors can integrate without forcing runtime-core to become a large platform. |
+| Multi-language runtime contract | Python, Go, TypeScript, and Rust implementations align on a language-neutral runtime contract and shared conformance fixtures. |
+## Why It Is Different From Agent Frameworks
+Agent frameworks usually own planning, reasoning, graph routing, prompt strategy, and model/tool selection. AgentLedger owns the reliability boundary around execution:
+```text
+Agent framework:
+  choose what should happen next
+AgentLedger:
+  make the execution durable, governed, auditable, replayable, and recoverable
+```
+This means AgentLedger is designed to be used with existing frameworks rather than compete with them. A LangGraph, OpenAI Agents SDK, CrewAI, AutoGen, LlamaIndex, Semantic Kernel, or custom agent can keep its own reasoning model while AgentLedger records durable runtime evidence and governs side effects.
+## Current Stage
+AgentLedger is a young project. Its current value should be evaluated by infrastructure depth and clarity of contract rather than by broad adoption metrics alone.
+What is already in place:
+- stable v1.x runtime-core contract
+- Python reference implementation
+- Go, TypeScript, and Rust runtime-core parity gates
+- Tool Ledger, evidence/replay, policy/approval/sandbox boundaries, cost/failure attribution, worker/conformance, and adapter seams
+- optional package boundaries for storage, observability, sandbox, framework, and protocol adapters
+- formal documentation for architecture, runtime specification, storage, adapters, maturity, release checks, and language parity
+What remains intentionally separate or later-stage:
+- hosted dashboard products
+- full eval platforms
+- RAG/vector memory systems
+- production claims for every external backend
+- replacing mature workflow, tracing, or sandbox infrastructure
+## Open Source Maintenance Value
+AgentLedger is useful to maintain as open source because the problem is shared across the agent ecosystem. Different teams may use different agent frameworks and deployment stacks, but they face similar runtime reliability questions:
+- Which side effects happened?
+- Which tool calls were approved?
+- Which state version was used?
+- Can this run be resumed?
+- Can this result be reproduced?
+- Can this failure be attributed?
+- Can a new agent version be compared against historical evidence?
+Open development makes the runtime contract, adapter boundaries, conformance fixtures, and examples easier to review and reuse across ecosystems.

agentledger-runtime 1.2.3__tar.gz → 1.2.4__tar.gz

agentledger-runtime 1.2.3tar.gz → 1.2.4tar.gz