v0.1.2 — JSON-safe normalization for LangGraph ToolCall path

Patch release. Hotfixes a real bug surfaced by a runnable LangGraph example against create_react_agent.

📦 PyPI: https://pypi.org/project/rootsign/0.1.2/
🐛 Fixes: ACTION_RECORD insertion crashed under LangGraph's canonical ToolNode / create_react_agent path.

What changed

When a tool is invoked through LangChain's ToolCall envelope (which is what ToolNode and create_react_agent use internally), BaseTool.ainvoke wraps the tool's plain-string return into a ToolMessage before returning. Before v0.1.2, _emit_action_record stored that raw return directly into the output_redacted JSONB column — and ToolMessage isn't JSON-serializable, so the INSERT crashed and the action never landed:

PendingRollbackError: ... Original exception was:
Object of type ToolMessage is not JSON serializable

v0.1.2 adds _to_json_safe in rootsign/sdk/decorator.py and applies it to both input_payload and output_payload before redaction and hashing. LangChain BaseMessage duck-types (anything with .content and a string .type) are coerced to {"_message_type": <type>, "content": <recursed content>} — preserving the agent's intent without dragging in per-run noise fields like tool_call_id or usage_metadata that would destabilize input hashes. Anything genuinely non-serializable falls back to str(value) so the hash never explodes.

Compatibility

• Plain tool.ainvoke({dict}) callers — unchanged. Hash bytes are byte-for-byte identical to v0.1.1.
• Chains emitted by v0.1.0 / v0.1.1 with plain-string tool returns — continue to verify cleanly under v0.1.2. compute_action_self_hash is unchanged.
• Chains attempted under v0.1.1 with create_react_agent — there aren't any; the INSERT crashed before they could be written.

Tests

20 new cases in tests/unit/test_emit_action_record_json_safe.py lock in _to_json_safe's contract (primitives, nested dicts/lists, BaseMessage shape, private-field drop, arbitrary-object fallback, determinism) plus an end-to-end ToolCall envelope + ToolMessage return path through _emit_action_record. Full unit suite green (243/243). Show HN hard gate (tests/integration/test_show_hn_quickstart.py) and HiTL CLI integration tests green post-change.

Who should upgrade

Everyone running LangGraph through ToolNode or create_react_agent. pip install -U rootsign[langgraph] picks v0.1.2 automatically — no API surface change.

v0.1.1 — Phase 1 launch (PRD-19 opt-in decision capture)

First public release. pip install rootsign[langgraph] (or [crewai]) on Python 3.11–3.14.

📦 PyPI: https://pypi.org/project/rootsign/0.1.1/
📖 README: https://github.com/Providex-AI/rootsign#readme

Highlights

• Opt-in decision capture (ADR-008). Set ROOTSIGN_CAPTURE_DECISIONS=true and call ctx.record_decision(...) to record the agent's reasoning before a tool call. The next Action is linked via decision_id. Out-of-chain by design — verify_chain is unchanged. Tunable persistence depth via ROOTSIGN_REASONING_DEPTH (minimal / summary / full).
• SDK_VERSION from importlib.metadata. Single source of truth — no more hand-pinned drift across decorator.py / session.py.
• Pre-launch security hardening (already in 0.1.0.dev):
  • HiTL approval context now passes the redacted input to the operator-facing context_presented field — raw PII no longer persists on timeout.
  • Redaction depth limit fails closed — subtrees past MAX_REDACTION_DEPTH return [REDACTED] instead of passing raw data through.
  • verify_session_local uses compute_action_self_hash (matches the store), so real exported chains no longer falsely report TAMPERED on record #1.

What's in the box

Surface	Shipping
@rootsign.trace decorator	✅
LangGraph integration (wrap_tools)	✅
CrewAI integration (wrap_crewai_tools) — tested against 0.28 / 0.40 / 1.x	✅
Hash chain + rootsign verify <session-id> CLI	✅
Local JSONL verification (rootsign verify --local)	✅
PII redaction (StandardPIIConfig / FinancialPIIConfig / HealthcarePIIConfig)	✅
Human-in-the-loop checkpoint (require_approval=True) + rootsign approve CLI	✅
Opt-in decision capture (PRD-19 / ADR-008)	✅
rootsign-admin operator CLI (start-db, init, status)	✅

Architecture pointers

• docs/adr/ADR-001 — canonical hash spec (frozen)
• docs/adr/ADR-002 — ingest failure isolation
• docs/adr/ADR-006 — redaction contract
• docs/adr/ADR-007 — HiTL checkpoint design
• docs/adr/ADR-008 — decision capture out-of-chain pattern (PRD-19)

Coming next (Phase 2)

• HttpIngestClient + hosted compliance dashboard — drop-in replacement for LocalIngestClient
• Browser-based HiTL approval (no CLI required)
• AutoGen integration

—

Apache-2.0. Issues and PRs welcome at https://github.com/Providex-AI/rootsign/issues.

RootSign v0.1.0 — Phase 1 MVP

RootSign v0.1.0 — Phase 1 MVP

Tamper-evident provenance logging for AI agents.

This is the first publishable release of RootSign — the SDK ships with
LangGraph and CrewAI integrations, a rootsign verify CLI, PII redaction,
and human-in-the-loop checkpoints. Local first; Postgres + TimescaleDB.

---

What's included

Framework integrations

• LangGraph 0.1.x and 0.2.x — @rootsign.trace, rootsign.wrap_tools(). See ADR-004.
• CrewAI 0.28, 0.40, and 1.x — CrewAITracer.wrap_tools(),
  rootsign.wrap_crewai_tools(). Duck-typed interception so future
  versions Just Work. See ADR-005.

Core SDK

• SHA-256 hash chain across every Action record in a session. verify_chain
  detects any after-the-fact modification.
• Human-in-the-loop checkpoint — @rootsign.trace(require_approval=True)
  blocks tool execution until a human approves via the CLI. Async poll
  loop, configurable timeout. See ADR-007.
• Approval records with three terminal states: human_approved,
  human_rejected, timed_out (forensically distinct from rejected —
  "nobody responded" vs "someone said no").
• PII redaction before hashing so stored hashes carry no PII signal.
  Three ready configs: StandardPIIConfig (email/phone/SSN/CC/UK NI),
  FinancialPIIConfig (+ account/routing/IBAN), HealthcarePIIConfig
  (+ MRN/NPI/DOB). See ADR-006.
• rootsign.session() async context manager — auto SESSION_OPEN /
  SESSION_CLOSE.

CLIs

• rootsign verify <session_id> — verifies the hash chain. Exit 0 = VALID, 1 = TAMPERED.
• rootsign verify --local <path.jsonl> — offline JSONL verification, no DB required.
• rootsign approve <action_id> — approve a pending HiTL action.
  --reject --reason "..." for rejection; --list to see what's pending.
• rootsign-admin init — schema migration (alembic upgrade head).

Storage

• PostgreSQL 16 + TimescaleDB 2.14 (local dev via docker-compose).
• LocalIngestClient — in-process ingest, no HTTP required.
• Cloud HttpIngestClient reserved for Phase 2.

---

Architecture decisions captured

ADR	Topic
ADR-001	Hash canonical spec
ADR-002	Transport-agnostic client
ADR-003	Framework contract tests
ADR-004	LangGraph interception
ADR-005	CrewAI interception
ADR-006	Redaction contract
ADR-007	HiTL checkpoint design

---

Known limitations

These are deliberate Phase 1 scope decisions, all on the Phase 2 roadmap:

• No cloud ingest backend. HttpIngestClient raises
  NotImplementedError. Phase 2.
• No web dashboard. Audit history queries are SQL today; the hosted
  compliance dashboard is the Phase 2 deliverable.
• HiTL is plain-async-callable only. @rootsign.trace(require_approval=True)
  on a LangChain BaseTool or CrewAI tool raises NotImplementedError
  with a "wrap the underlying function" hint. Lifting the gate needs an
  output-capture write-back RPC — Phase 2.
• Output not chain-captured for HiTL actions. output_hash stays
  NULL for actions gated on human approval. The input is chained; the
  output reaches the caller but isn't part of the audit hash.
• AutoGen and TypeScript SDKs not yet shipped. Both deferred to
  RootSign v1.0 alongside the Phase 2 cloud backend.

---

Install

pip install rootsign[langgraph]   # LangGraph
pip install rootsign[crewai]      # CrewAI

Pre-PyPI note (until publish): install from source —
pip install 'rootsign[langgraph] @ git+https://github.com/Providex-AI/rootsign.git'.

Python 3.11 or 3.12 recommended. The [crewai] extra currently lags
on 3.13 / 3.14 wheels. If you hit No matching distribution found for crewai,
switch to Python 3.12.

---

Quickstart

See README.md for the full LangGraph + CrewAI quickstarts.
The CI-runnable reproducibility test is at
tests/integration/test_show_hn_quickstart.py
— that's the same flow the README walks you through.

---

Stats

• 18 test modules touched, 297 tests passing.
• 7 architecture decisions documented.
• Framework contract tests green on LangGraph 0.1.x / 0.2.x and
  CrewAI 0.28 / 0.40 / 1.x.

---

Contributors

This release is the work of:

• Providex AI — design, implementation, releases

Reach out: info@getprovidex.com · github.com/Providex-AI/rootsign

---

License

Apache License 2.0 — see LICENSE and NOTICE.