Release: x402 settle-first + scenario hardening

Version: 2026.22.4
Date: May 28, 2026
Author: Raahul Dutta

OVERVIEW

This release closes issue #562 — the verify-vs-settle gap in Bindu's
x402 payment middleware — in two steps.

First (#563): a failed settlement no longer delivers the artifact. The
worker now gates artifact delivery on settle success, and persists the
EIP-3009 nonce, full authorization, and network on every failed-settle
path so an operator can reconcile against the chain instead of seeing
only str(e) buried in metadata.

Second (#565): settlement now happens BEFORE the agent runs, not after.
A drained wallet, a parallel-nonce race, or a validBefore lapse now
costs the agent zero LLM tokens — the worker exits before any state
transition or model call. This matches Google's A2A x402 extension
choice for long-running agent workloads (the closest peer protocol);
total wall-clock on the happy path is unchanged because the settle
latency moves rather than adds. The companion failure mode — work
raising after a successful settle — is tagged payment-orphaned in
metadata so the operator can reconcile manually.

The release also ships an end-to-end demo (tests/e2e/x402_scenarios/)
that boots a real Bindu agent + a programmable fake facilitator and
walks through all four #562 scenarios via real HTTP, and bumps two
dependency groups (OpenTelemetry 1.42 / 0.63b1, Starlette 1.0).

BREAKING CHANGES

None for users of the public A2A protocol. Internal worker API:
ManifestWorker._handle_terminal_state no longer accepts
payment_context (replaced by settlement_metadata, computed upfront
in run_task). Anyone subclassing the worker should update accordingly.

IMPROVEMENTS

🎯 Features

• feat(x402): adopt settle-first ordering + E2E scenario coverage (#565)

🐛 Bug Fixes

• fix(x402): gate artifact delivery on settlement success (#562) (#563)
• fix(x402): keep facilitator error detail out of the user-facing
  failure message (CodeRabbit follow-up to #563)
• fix(x402): loguru positional placeholders in _settle_payment —
  a latent bug surfaced by the live E2E demo where JSON-bearing
  exception strings caused logger.error to raise KeyError and
  silently swallow the recovery-metadata return

📦 Chores / Deps

• chore(deps): bump starlette 0.49.1 → 1.0.0 (#559)
• chore(deps): bump opentelemetry 1.35.0 → 1.42.1 and the matching
  instrumentation 0.56b0 → 0.63b1 (#556)

📚 Docs

• docs(known-issues): add x402-settle-false-negative-silent-orphans
  and x402-no-auto-refund-for-orphan-payments medium entries (#566)
• docs(payment): explain settle-first ordering, the orphan-payment
  failure mode, and point at the live E2E demo
• docs(inbox): refresh inbox screenshot
• docs(readme): promote the mTLS + Hydra + DID story to its own section
• docs: add SECURITY_STACK.md explaining mTLS + Hydra + DID together

KNOWN LIMITATIONS (NEW)

Settle-first closes the LLM-cost half of the verify/settle gap but
introduces a quieter failure mode: facilitator timeout vs Base
confirmation race. Two new entries in bugs/known-issues.md:

• x402-settle-false-negative-silent-orphans — facilitator /settle can
  time out while the chain confirms anyway. Reconciliation worker
  (which would query AuthorizationUsed events and reverse the
  failed-task tag) is scoped out as a follow-up. EIP-3009 fields
  are persisted on every failed-settle task for manual reconciliation.

• x402-no-auto-refund-for-orphan-payments — when orphans exist,
  refunding requires a manual USDC transfer. Bindu doesn't manage an
  outbound wallet today (pay_to is a config string only). Scoped out
  because of the custody surface — revisit when there's real volume
  to justify it.

Both entries include the operator workaround using the metadata we
now persist.

TECHNICAL DETAILS

Files Modified: 13
Lines Added: +1905
Lines Removed: -111

Test surface (post-merge):

• 139 x402-touching unit + integration tests pass
• 4 end-to-end scenario tests in tests/integration/x402/test_e2e_scenarios.py
• A runnable subprocess demo at tests/e2e/x402_scenarios/run_e2e.py

TESTING

✅ All unit tests passing (per-PR CI green on #563, #565, #556, #559, #566)
✅ All integration tests passing
✅ Pre-commit hooks passing (ruff, ruff-format, ty, bandit, detect-secrets, pydocstyle)
✅ Live end-to-end demo exercises all four #562 scenarios against
a real Bindu agent via real HTTP

COMMIT DETAILS

Key commits since 2026.21.1:

• 7905ea6: docs(known-issues): add two payment-related medium entries (#566)
• b3f2cfe: chore(deps): bump starlette from 0.49.1 to 1.0.0 (#559)
• 4f33633: chore(deps): bump the production group across 1 directory with 6 updates (#556)
• 1a085f5: feat(x402): adopt settle-first ordering + E2E scenario coverage (#565)
• c6b726c: fix(x402): gate artifact delivery on settlement success (#562) (#563)
• 8d4b07a: docs(inbox): refresh inbox screenshot
• 6c80846: docs(readme): promote the mTLS + Hydra + DID story to its own section
• d16b086: docs: add SECURITY_STACK.md explaining mTLS + Hydra + DID together

USAGE WITH GIT

View this release

git show 2026.22.4

Compare to previous release

git diff 2026.21.1..2026.22.4 --stat

Reproduce the live demo

uv run python tests/e2e/x402_scenarios/run_e2e.py

LINKS

• Issue: #562
• Artifact-gate PR: #563
• Settle-first PR: #565
• Known-issues PR: #566
• Compare: 2026.21.1...2026.22.4

Release: bindu-communication Inbox and Secured Outbound A2A
Version: 2026.20.7
Date: May 17, 2026

OVERVIEW

This release ships bindu-communication, an operator inbox for watching
agent-to-agent traffic, together with the authentication and
observability work that lets it talk to Hydra-protected peers
end-to-end. The inbox is a three-pane Gmail-shape surface backed by
SQLite that stitches outbound sends, agent webhooks, and gateway plan
traces into one conversation per A2A context_id. Outbound calls are
now JWT-bearer plus DID-signed using the operator's personal agent as
the signing identity, so the same operator can compose against any
peer that enforces AUTH__ENABLED=true. The gateway gets a stateless
Path A refactor (it no longer owns a session DB; the client carries
history per /plan call) and a fix for AI SDK v6 tool-error chunks so
peer failures surface in the trace instead of disappearing into a
hanging task-started row.

PROBLEM SOLVED

Before this release:

• The bindu-communication scaffold was a visual prototype against mock
  data. There was no SQLite persistence, no wired-up SSE, no thread
  grouping, no compose flow, and no real authentication on outbound
  sends. The "Register agent" affordance was UI theatre that didn't
  produce real registrations.
• Outbound A2A from the comms server to any Hydra-protected peer
  returned JSON-RPC error -32009 ("Authentication is required")
  wrapped inside HTTP 200. The compose flow surfaced this as a
  silent "HTTP 200 with red X" with no actionable signal.
• Multi-agent plans through the gateway also failed: the comms server
  declared auth: { type: "none" } on every plan-catalog entry, so the
  gateway sent unauthenticated requests, got 403s, then silently
  swallowed those tool errors because session/prompt.ts had no
  "tool-error" case in its AI SDK chunk switch. The planner LLM saw
  missing tool results and invented plausible-sounding explanations
  like "authentication is not available in this session" — making it
  impossible for the operator to tell hallucination apart from real
  outage.
• When peer calls did fail, the comms inbox showed a task-started row
  with no terminal state and no error body. From the operator's
  perspective the call simply hung forever.
• Gateway owned its own session DB, duplicating state the client
  already had. This made the gateway stateful where it didn't need to
  be and complicated per-plan isolation.
• The frontend/ SvelteKit POC was sitting unused alongside the new
  bindu-communication tree, doubling the surface area to maintain.

After this release:

• bindu-communication is a real product surface: three-pane Gmail
  layout (folders + thread list + thread view), SQLite event store,
  server-side thread state and first-contact tracking, real-time SSE
  of inbound webhooks and outbound sends, threads grouped by
  context_id with stitching across the outbox and per-agent lanes,
  Inbox / Sent / Drafts / Archive folders, in-folder search, bulk
  select, hover actions, autosaved draft compose, read tracking, and
  reply-in-thread that resumes the existing task when the previous
  state is still open.
• Outbound message/send now authenticates correctly. The comms server
  mints short-lived Hydra access tokens via the client_credentials
  grant using the personal agent's OAuth client credentials at
  ~/.bindu/personal/.bindu/oauth_credentials.json (cached, refreshed
  60s before expiry), signs the exact request body with the personal
  agent's Ed25519 private key, base58-encodes the signature, and
  attaches X-DID / X-DID-Signature / X-DID-Timestamp on every send.
  The X-DID value is derived from the OAuth client_id so it always
  matches the JWT sub the verifier checks against.
• Comms now declares auth: { type: "did_signed" } on every plan-
  catalog entry it sends to the gateway. The gateway uses its own
  pre-registered DID identity (BINDU_GATEWAY_DID_SEED) to mint a
  token and sign peer calls. Multi-agent plans actually invoke peers
  now and the planner synthesizes real results.
• AI SDK v6 tool-error chunks are handled. When a peer call throws
  (any HTTP 4xx/5xx, network failure, schema mismatch), the gateway
  updates the ToolPart to status="error", publishes ToolCallEnd with
  the error string, and the SSE bridge emits task.finished with
  state="failed" and the error body. The comms inbox renders these
  as failed rows with the error text inline — no more hanging
  task-started rows and no more planner hallucination about what
  went wrong.
• Comms /api/plan synthesizes its own task-started / task-artifact /
  task-finished / plan-reply / plan-summary events from the gateway
  SSE stream and persists them. The inbox liveStream mapper
  recognises every kind, normalises state, strips the
  <remote_content> wrapper from artifact bodies, and renders the
  planner reply with a "self" trust pill.
• Gateway is stateless on the new Path A. The client owns the session
  record and posts history+prior_summary on every /plan call; the
  gateway carries no DB.
• frontend/ POC is removed; bindu-communication is the only operator
  UI in tree.

PERSONAL AGENT (new)

A wizard inside the inbox sidebar spawns a server-side bindufied
agent under ~/.bindu/personal/. The directory holds:

• agent.py — auto-generated from the persona JSON; bindufy()
  invocation with OpenRouter as the model provider and an in-process
  Pipedream Connect MCP wiring (Gmail / Notion) added per connected
  account.
• persona.json — the persona traits, interests, occupation. Editing
  this is the supported way to change the agent.
• .env — model + Pipedream env vars (OPENROUTER_API_KEY,
  OPENROUTER_MODEL, PIPEDREAM_, AUTH__ENABLED, HYDRA__). 0600.
• .bindu/private.pem + public.pem — Ed25519 keypair for DID
  signatures. 0600 on the private key.
• .bindu/oauth_credentials.json — Hydra OAuth client metadata
  registered at first boot; the deterministic client_secret derived
  from the Ed25519 seed.

The wizard handles spawn/stop. Stop is graceful; restart is a
relaunch of the same persona. The personal agent serves
/.well-known/agent.json publicly (standard A2A discovery) and
rejects unauth message/send (AUTH__ENABLED=true, Hydra introspection
plus DID signature mandatory). It is the operator's signing identity
for everything the comms server sends outbound — without it, sends
fall back to did:bindu:operator:local and most peers will reject.

GATEWAY_TEST_FLEET

Five example agents now run on dedicated ports with published skill
metadata:

• joke_agent port 5773 skill tell_joke
• math_agent port 5775 skill calculate
• poet_agent port 5776 skill write_poem
• research_agent port 5777 skill research
• bindu_docs_agent port 5778 skill bindu_docs_qa (was faq_agent)

A new examples/gateway_test_fleet/hydra_smoke_test.sh exercises the
full auth path against a chosen agent (token mint + signed send) and
prints a pass/fail summary. Useful as a one-shot health check after
restarts or config changes.

OPERATIONAL CHANGES

• SSE auth in comms now uses ?token query param (browsers cannot set
  custom headers on EventSource), in addition to Authorization
  Bearer for fetch-based clients.
• Webhook endpoint validates the agentId path segment and optionally
  requires BINDU_WEBHOOK_TOKEN.
• SSRF allowlist on the lifecycle webhook forwarder was dropped (was
  causing more friction than the security marginal it gained;
  webhooks are authenticated downstream by AUTH__ENABLED anyway).
• Agent prompts on intermediate states (input-required, payment-
  required, auth-required) are now forwarded on the lifecycle
  webhook so the comms inbox can render the agent's question
  inline; previously the operator only saw the state pill.
• UUID serialization in the server fixed (was emitting non-RFC
  strings under certain task-transition orderings).
• TinyTroupe references removed from the persona scaffolding —
  unused vendor code that was confusing new operators.

FILES OF NOTE

Comms server (TypeScript, hono):

• bindu-communication/server/index.ts — ~600 lines added: SSE feed,
  outbound compose with Hydra+DID auth, /api/plan stream ingestion,
  webhook handler, personal-agent endpoints, thread state.
• bindu-communication/server/personal-agent.ts — spawn/stop, render
  agent.py from persona, register Hydra client.
• bindu-communication/server/db.ts — SQLite schema for events,
  agents, contexts, thread_state, personal_agent, settings.

Comms UI (React 19 + React Router v7):

• bindu-communication/src/lib/liveStream.ts — webhook -> StreamEvent
  mapper; gateway-event + outbound + plan-trace dispatch.
• bindu-communication/src/lib/threads.ts — context_id grouping +
  cross-lane stitching.
• bindu-communication/src/components/* — Sidebar, ThreadList,
  ThreadView, DetailRail, ComposeModal, PersonalAgentWizard,
  AddAgentModal, AgentInfoModal, SettingsModal.

Gateway:

• gateway/src/session/llm.ts — tool-error chunk added to StreamEvent
  union; AI SDK chunk mapper handles the new case.
• gateway/src/session/prompt.ts — tool-error case in the switch
  updates ToolPart state and publishes ToolCallEnd with error.
• gateway/src/comms-forwarder.ts — forwards bus events to the
  comms /webhooks endpoint when BINDU_COMMS_URL is set.
• gateway/src/api/plan-route.ts — already knew how to read
  ToolCallEnd.error and emit task.finished {state: "failed", error}.

Examples:

• examples/gateway_test_fleet/*.py — ports moved to 5xxx,
  AgentSkill metadata added.
• examples/gateway_test_fleet/hydra_smoke_test.sh — new.

Removed:

• frontend/ — entire SvelteKit POC tree.

KNOWN ISSUES

• Plan-trace task-started rows render with agent_did=null in the
  counterparty position. The resolved DID from the fetched
  AgentCard is held in observedByName at the gateway boundary but
  is not threaded into the task-started SSE frame (only
  task-artifact / task-finished re...

Release: Document Analyzer & Reliability Improvements
Version: 2026.12.5
Date: March 19, 2026

OVERVIEW

Maintenance and feature release focused on document analysis, payment robustness, scheduler and storage reliability, and usability improvements across the UI and configuration. This release also introduces a DSPy agent example, structured LangGraph workflow integration, and multiple accessibility and documentation enhancements contributed by the community.

PROBLEM SOLVED

Before this release:

• Document analyzer examples did not consistently propagate extracted text into FilePart.text, making downstream processing and testing harder
• Scheduler and storage subsystems had edge‑case issues (AnyIO deadlock, CPU burn, potential OOMs) and inconsistent formatting
• Multi‑currency and multi‑asset payment flows were harder to configure safely, leading to possible duplicate or partial payment contexts
• Several examples and configs had missing dependencies or unclear requirements, increasing setup friction for new users

After this release:

• Document analyzer reliably preserves FilePart.text, supports PDF/DOCX mimetypes, and ships with dedicated tests
• Storage, scheduler, Hydra middleware, and TaskManager are hardened with improved error handling and concurrency safety
• Payment features seamlessly support multiple currencies and multi‑asset requirements with strict context validation
• Examples and docs are updated with DSPy, LangGraph workflows, explicit API key prerequisites, and improved READMEs

FEATURES

1. Document Analyzer Agent & Frontend Integration

   • Adds a dedicated document analyzer agent with skills wiring and workflow examples for document processing
   • Frontend explicitly allows PDF and DOCX mimetypes and handles animated formats appropriately
   • Ensures uploaded FilePart objects preserve the text property so downstream handlers can operate on content
   • Includes dedicated .env and skill.yaml files for immediate plug-and-play usage

2. DSPy Agent & Structured LangGraph Workflows

   • Introduces a new DSPy agent example in examples/beginner/ demonstrating question-answering behavior
   • Adds comprehensive unit tests for the DSPy example to validate behavior and guard against regressions
   • Integrates a structured LangGraph workflow example to showcase advanced orchestration patterns within Bindu

3. Payments & Multi‑Currency Support

   • Extends payment logic allowing agents to accept multiple payment currencies in a single configuration
   • Implements multi‑asset payment requirements with improved payment context validation
   • Fixes duplicate payment context injection in the A2A message/send endpoint
   • Prevents 500 Server Errors when payment states are only partially set or malformed

4. Storage, Scheduler, and Auth Reliability

   • Refactors the storage layer to harden the in‑memory subsystem, reduce OOM risks, and optimize database indexing
   • Fixes scheduler behavior to resolve AnyIO buffer deadlocks, CPU burn loops, and trace serialization issues
   • Migrates Hydra auth middleware to a pure ASGI implementation for concurrency, WebSocket support, and lifecycle handling

5. UI & Accessibility Enhancements

   • Introduces a collapsible Agent Inspector with clearer empty states for a better first-agent experience
   • Adds skip‑to‑content links and main landmarks to improve screen-reader accessibility and keyboard navigation
   • Eliminates UI flicker when switching between previous chats, improving perceived responsiveness

6. Configuration & Validation Improvements

   • Adds fail‑fast validation for required deployment.url in agent configuration
   • Improves nested required field validation with much clearer developer error messages
   • Moves key settings constants into dedicated modules to clarify configuration boundaries

7. Documentation Updates

   • Refreshes README with improved visuals (header/footer, quotes) and clearer getting-started guidance
   • Documents API key prerequisites (including in the Hindi README) to ensure external providers are configured correctly
   • Refreshes .env examples to reflect newer dependencies (e.g., OpenRouter)
   • Fixes broken links in translated READMEs and aligns license/test‑coverage docs

8. Testing & Code Quality

   • Expands TaskManager tests to cover edge cases, lifecycles, and security scenarios
   • Adds robust tests for TaskHandlers, ContextHandlers, MessageHandlers, and A2A payment validations
   • Cleans up legacy styling, trailing whitespaces, docstrings, and makes Coveralls upload non-blocking

TECHNICAL DETAILS

Document Analyzer Flow:

1. Frontend restricts file uploads to strictly allowed mimetypes (PDF, DOCX).
2. Uploaded file parts are preserved in transport, explicitly keeping FilePart.text intact.
3. Backend analyzer extracts the text and injects it into the pipeline for downstream handlers.

Payment & Context Handling:

• Payment contexts now natively support arrays of multi-currency and multi-asset requirements.
• The A2A routing layer guarantees the payment context is injected exactly once and stripped when not needed, preventing duplicate state data.

Scheduler & Storage Behavior:

• The scheduler loop execution now safely avoids AnyIO buffer deadlocks and busy‑loop CPU consumption.
• Trace serialization is restructured to safely handle massive or complex trace payloads without failing.

Auth Middleware:

• The Hydra middleware bypasses the synchronous event loop and runs as Pure ASGI.
• Stream lifecycle handlers strictly manage connection drops to prevent resource leaks in concurrent environments.

CONFIGURATION

Environment Variables (Example):

# Agent Deployment URL is now strictly validated
DEPLOYMENT__URL=http://localhost:3773

# Required for the DSPy / Document Analyzer examples
OPENROUTER_API_KEY=sk-or-v1-...

BREAKING CHANGES

• Stricter Configuration Validation
  • Impact: Previously misconfigured deployments missing a deployment.url or nested fields will now fail fast on boot instead of failing silently later.
  • Migration: Ensure your agent_config.json includes all strictly required deployment routing fields.
• Constants Reorganization
  • Impact: Example projects relying on older, deeply imported constants may fail to import.
  • Migration: Update your imports to use the new dedicated constants modules.

MIGRATION NOTES

For Existing Deployments:

1. Review agent configurations and ensure deployment.url is properly set.
2. Confirm any custom payment configurations map correctly to the new multi-currency validation rules.
3. If you use custom scheduler, storage, or Hydra auth extensions, rebase your forks onto the new modules to inherit the deadlock and ASGI safety fixes.

For New Deployments:

1. Use the new DSPy, LangGraph, or Document Analyzer templates to bootstrap advanced agents.
2. Base your initial .env and skill.yaml files strictly on the newly provided examples to ensure all API prerequisites are satisfied.
3. Consult the updated API prerequisites section in the README.

SECURITY CONSIDERATIONS

• Pure ASGI Hydra middleware significantly reduces the attack surface for slowloris/DoS attacks.
• Tightened exception blocks prevent the system from swallowing errors and masking hidden failures.
• Strict payment context validation prevents bad actors from spoofing billing or corrupting payment states.

PERFORMANCE IMPACT

• CPU: Eliminated busy-wait loops in the scheduler during edge cases, vastly reducing idle CPU overhead.
• Memory: Storage refactors reduce RAM pressure on massive datasets via optimized DB indexing.
• UX: Rendering performance improved by eliminating visual flicker during chat history navigation.

TESTING

✅ Unit tests for TaskManager edge cases, lifecycle, and security behavior
✅ Tests for TaskHandlers, ContextHandlers, MessageHandlers, and A2A payment validations
✅ Document analyzer tests for file‑part text propagation and mimetype handling
✅ Additional tests for auth, configuration validation, and example dependencies
✅ All existing test suites updated and passing

FILES CHANGED

New Files:

• Document analyzer agent codebase, skill.yaml, and .env.example
• examples/beginner/dspy_example.py (and associated unit tests)
• LangGraph structured workflow example

Modified Files:

• Scheduler and storage modules (deadlock/OOM hotfixes)
• Hydra auth middleware (ASGI migration)
• Payment/A2A handlers (multi-currency handling)
• UI components (Agent Inspector, flicker fix, ARIA attributes)
• Configuration validation (deployment checks, constants refactoring)
• All localized README.md variations

DOCUMENTATION

• Updated UI elements on READMEs with modern styling
• Expanded setup docs including explicit API provider prerequisites
• Fixed localization routing for Hindi documentation
• Adjusted Test Coverage and License notes to match CI workflows

TEST COVERAGE IMPROVEMENTS

Major expansion of test coverage and code quality improvements:

Coverage Metrics:

• Increased from 58.59% to 60.11% (+1.52% improvement)
• Total: 688 tests passing with 7 warnings
• Coverage threshold adjusted from 64% to 60% for realistic targets

New Tests Added (44 total):

• ManifestWorker: +15 comprehensive async tests

  • Task execution flows (basic, input-required, auth-required)
  • Payment context integration and settlement
  • Agent error handling and recovery
  • System message injection with structured responses
  • Context-based history building
  • Coverage improved: 58.29% → 82.89% (+24.6%)

• BinduApplication: +20 initialization tests

  • Configuration validation (storage...

Release: Vault Integration for Persistent Agent Identity
Version: 2026.9.4
Date: February 25, 2026

OVERVIEW

Major feature release adding HashiCorp Vault integration for persistent storage
of DID keys and Hydra OAuth2 credentials. This solves the critical issue where
pod restarts in Kubernetes deployments resulted in new agent identities and
orphaned Hydra OAuth clients.

PROBLEM SOLVED

Before this release, when a pod died and restarted:
❌ New DID keys were generated → different agent identity
❌ New Hydra OAuth client was registered → orphaned clients in Hydra
❌ Authentication broke → clients couldn't authenticate with new credentials

After this release, with Vault enabled:
✅ DID keys are restored from Vault → same agent identity
✅ Hydra credentials are reused → no duplicate clients
✅ Authentication persists → seamless pod restarts

FEATURES

1. Vault Client Module (bindu/utils/vault_client.py)

   • Store and retrieve DID private/public keys
   • Store and retrieve Hydra OAuth2 credentials
   • Automatic backup and restore functionality
   • Graceful fallback when Vault is unavailable
   • Reuses existing AsyncHTTPClient for efficiency (no duplicate HTTP clients)
   • Proper async session cleanup to prevent memory leaks

2. Deterministic Agent Identity

   • Agent ID generated deterministically from SHA256(author:agent_name)
   • Same author + name → same agent_id → same DID every time
   • No need to hardcode agent IDs in configuration
   • Automatic persistent identity without manual intervention

3. DID Setup Integration

   • Changed default: recreate_keys=False (was True)
   • Checks Vault for existing keys before generating new ones
   • Automatically backs up newly generated keys to Vault
   • Restores keys from Vault on pod restart
   • Uses correct filenames from settings (private.pem, public.pem)

4. Hydra Registration Integration

   • Priority 1: Check Vault for existing credentials
   • Priority 2: Check local filesystem
   • Priority 3: Generate new credentials
   • Automatic backup of credentials to Vault
   • Reuses client_secret from Vault when recreating clients
   • Proper VaultClient session cleanup in all code paths

5. Configuration

   • Environment variables: VAULT__ENABLED, VAULT__URL, VAULT__TOKEN
   • Alternative names: VAULT_ADDR, VAULT_TOKEN
   • Updated VaultSettings with comprehensive documentation
   • Vault config loaded from environment before DID initialization

6. Documentation

   • Complete guide: docs/VAULT_INTEGRATION.md
   • Example configuration: .env.vault.example
   • Kubernetes deployment examples
   • Vault setup instructions
   • Troubleshooting guide

7. Testing

   • Comprehensive unit tests: tests/unit/test_vault_integration.py
   • Tests for all Vault operations
   • Mock-based testing for CI/CD compatibility
   • Updated tests to use correct DID key filenames

8. Type Safety & Code Quality

   • Proper UUID type handling throughout codebase
   • Type-safe agent_id conversion (UUID for internal, str for display)
   • No unclosed aiohttp client sessions
   • Removed unused dependencies (agno, openai, ddgs)

TECHNICAL DETAILS

Storage Hierarchy:
vault/secret/bindu/
├── agents/{agent_id}/did-keys
│ ├── private_key (PEM)
│ ├── public_key (PEM)
│ └── did
└── hydra/credentials/{did}/
├── client_id
├── client_secret
├── agent_id
├── created_at
└── scopes

Agent ID Generation:

1. If no explicit ID in config: SHA256(author:agent_name)[:32] → UUID
2. Same author + name = same deterministic agent_id every time
3. Agent ID used in DID: did:bindu:{author}:{agent_name}:{agent_id}

Startup Flow:

1. Generate deterministic agent_id from author:agent_name
2. Check Vault for DID keys → restore if found → generate if not found
3. Check Vault for Hydra credentials → reuse if found → register if not found
4. Backup all credentials to Vault
5. Start agent with persistent identity

CONFIGURATION

Environment Variables:

# Enable Vault
VAULT__ENABLED=true

# Vault server URL
VAULT__URL=http://vault:8200

# Vault authentication token
VAULT__TOKEN=hvs.CAESIJ...

Kubernetes Example:

env:
- name: VAULT__ENABLED
  value: "true"
- name: VAULT__URL
  value: "http://vault.vault.svc.cluster.local:8200"
- name: VAULT__TOKEN
  valueFrom:
    secretKeyRef:
      name: bindu-vault-token
      key: token

BREAKING CHANGES

• DID setup default changed: recreate_keys=False (was True)
  • Impact: Existing keys are preserved by default
  • Migration: No action needed, this is the desired behavior
  • Override: Set recreate_keys=True to force regeneration

MIGRATION NOTES

For Existing Deployments:

1. Enable Vault in configuration: VAULT__ENABLED=true
2. Set Vault URL and token
3. Restart agents - they will automatically backup existing keys
4. Verify keys are in Vault
5. Test by deleting and recreating pods

For New Deployments:

1. Set up Vault (see docs/VAULT_INTEGRATION.md)
2. Configure environment variables
3. Deploy agents - keys will be automatically stored in Vault

Vault Setup:

# Enable KV v2 secrets engine
vault secrets enable -path=secret kv-v2

# Create policy
vault policy write bindu bindu-policy.hcl

# Generate token
vault token create -policy=bindu -ttl=720h

SECURITY CONSIDERATIONS

• Use Kubernetes auth instead of static tokens in production
• Rotate Vault tokens regularly
• Enable Vault audit logging
• Use TLS for Vault communication
• Never commit Vault tokens to git

PERFORMANCE IMPACT

• Startup time: +100-200ms for Vault lookups
• Network: Requires Vault connectivity
• Caching: Local files cached after Vault restore
• Failover: Falls back to local files if Vault unavailable

TESTING

✅ Unit tests for VaultClient operations
✅ DID key backup and restore
✅ Hydra credential backup and restore
✅ Graceful degradation when Vault disabled
✅ Error handling for network failures
✅ All existing tests passing

FILES CHANGED

New Files:

• bindu/utils/vault_client.py (VaultClient implementation)
• docs/VAULT_INTEGRATION.md (comprehensive integration guide)
• .env.vault.example (example Vault configuration)
• tests/unit/test_vault_integration.py (unit tests)
• release-notes/2026.9.4.txt (this file)

Modified Files:

• bindu/penguin/did_setup.py (Vault restore/backup integration)
• bindu/penguin/bindufy.py (deterministic agent_id, Vault config loading)
• bindu/auth/hydra/registration.py (Vault credential restore/backup, session cleanup)
• bindu/settings.py (VaultSettings documentation)
• bindu/penguin/config_validator.py (recreate_keys default changed to False)
• bindu/utils/config_loader.py (Vault config loading from environment)
• examples/beginner/.env (DATABASE_URL SSL fix)
• examples/beginner/.env.example (Vault configuration example)
• pyproject.toml (removed unused dependencies: agno, openai, ddgs)

DOCUMENTATION

• Complete integration guide: docs/VAULT_INTEGRATION.md
• Configuration examples: .env.vault.example
• API documentation in code docstrings
• Kubernetes deployment examples
• Troubleshooting guide

CONTRIBUTORS

• Raahul Dutta

REFERENCES

• HashiCorp Vault: https://www.vaultproject.io/docs
• Kubernetes Auth: https://www.vaultproject.io/docs/auth/kubernetes
• KV Secrets Engine: https://www.vaultproject.io/docs/secrets/kv/kv-v2

Release: Dependency Version Updates
Version: 2026.9.2.1
Date: February 23, 2026

OVERVIEW

Patch release to relax version constraints for uvicorn and pydantic, allowing
for better compatibility with newer versions and easier dependency resolution.

CHANGES

Dependency Updates:

• Relaxed uvicorn constraint: 0.34.1 → >=0.35
  • Allows newer uvicorn versions with bug fixes and improvements
  • Updated in both main dependencies and [core] extras
• Relaxed pydantic constraint: exact version → >=2.11.7
  • Already updated in previous release, included for completeness

Benefits:

• Better compatibility with ecosystem packages
• Easier dependency resolution
• Access to latest bug fixes and security patches
• Reduced dependency conflicts

BREAKING CHANGES

None

MIGRATION NOTES

• Run: uv sync to update dependencies
• No code changes required

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified

CONTRIBUTORS

• Raahul Dutta

Release: Dependency Version Updates
Version: 2026.9.2.1
Date: February 23, 2026

OVERVIEW

Patch release to relax version constraints for uvicorn and pydantic, allowing
for better compatibility with newer versions and easier dependency resolution.

CHANGES

Dependency Updates:

• Relaxed uvicorn constraint: 0.34.1 → >=0.35
  • Allows newer uvicorn versions with bug fixes and improvements
  • Updated in both main dependencies and [core] extras
• Relaxed pydantic constraint: exact version → >=2.11.7
  • Already updated in previous release, included for completeness

Benefits:

• Better compatibility with ecosystem packages
• Easier dependency resolution
• Access to latest bug fixes and security patches
• Reduced dependency conflicts

BREAKING CHANGES

None

MIGRATION NOTES

• Run: uv sync to update dependencies
• No code changes required

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified

CONTRIBUTORS

• Raahul Dutta

Release: Dependency Optimization and Auth Configuration
Version: 2026.9.2
Date: February 23, 2026

OVERVIEW

This release focuses on reducing installation footprint by making heavy agent frameworks
optional dependencies, and improving authentication configuration for public endpoints.

CHANGES

Dependency Optimization:

• Moved agent frameworks to optional [agents] extra
  • agno, langchain, langgraph, ollama, duckduckgo-search now optional
  • Install with: uv pip install bindu[agents]
  • Reduces default installation size significantly
• Core Bindu functionality remains in base installation
• Blockchain/payment features (x402, web3) still included by default

Authentication & Security:

• Added /agent/negotiation to public endpoints (no auth required)
• Cleaned up public endpoints configuration
• Removed unnecessary static file routes from auth bypass list
• Improved auth middleware configuration clarity

Release Process:

• Updated release workflow to use week-based CalVer (YYYY.W.D)
• Enhanced create-release skill with new versioning format

Code Quality:

• Removed static file paths from public endpoints configuration
• Updated secrets baseline

INSTALLATION OPTIONS

Minimal installation (core only)

uv pip install bindu

With agent frameworks (for examples)

uv pip install bindu[agents]

Development installation

uv pip install -e ".[agents]"

BREAKING CHANGES

None - Agent frameworks are still available, just optional

MIGRATION NOTES

• If you use agno, langchain, or ollama: install bindu[agents]
• If you only run custom agents: base installation is sufficient
• Existing installations will continue to work

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Dependency resolution verified
✅ Public endpoint authentication bypass confirmed

CONTRIBUTORS

• Raahul Dutta

Release: Bug Fixes and Community Contributions
Version: 2026.8.7
Date: February 21, 2026

OVERVIEW

This release includes important bug fixes for schema management, type checking improvements,
dependency updates, and several community-contributed example agents. Focus on stability,
code quality, and expanding the example library.

CHANGES

Bug Fixes:

• Fixed schema name truncation logic for DID-based multi-tenancy
• Fixed type checker error for sys.stdout.reconfigure call
• Fixed docstring formatting to comply with pydocstyle D209
• Stabilized task_manager.py

Features & Enhancements:

• Added paywall example agent demonstrating x402 payment integration
• Added news summarizer agent with local Ollama and DuckDuckGo integration
• Added cybersecurity newsletter agent with security hardening
• Added lightweight in-memory delivery metrics to NotificationService
• Enhanced health endpoint observability
• Added early validation for required author field
• Updated release workflow to use week-based versioning (YYYY.W.D)

Code Quality:

• Added feedback header to sentry.py
• Cleaned up whitespace and formatting across multiple files
• Updated secrets baseline with new line numbers
• Enhanced PR template with comprehensive review checklist
• Removed trailing whitespace and sanitized credentials in documentation

Dependency Updates:

• Updated pydantic: 2.11.3 → 2.12.5 (resolves fastmcp compatibility)
• Updated requests: 2.32.3 → 2.32.5 (resolves langchain-community compatibility)
• Updated sqlalchemy: 2.0.44 → 2.0.46
• Updated tenacity: 8.5.0 → 9.1.4
• Updated rich: 13.9.4 → 14.3.2
• Updated uvx requirement: <2.0 → <4.0

Community:

• Added GitHub Sponsors funding page
• Multiple community contributions merged (PRs #172, #195, #210, #211, #212, #215)

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Schema truncation test fixed and verified
✅ Type checking errors resolved

CONTRIBUTORS

• Raahul Dutta
• rautsoham03
• ssjgit08
• Krushna
• AseemPrasad
• Sharda2004196
• ssjgit08
• Krushna56

BREAKING CHANGES

None

MIGRATION NOTES

• If upgrading from versions with exact dependency pins, run: uv sync
• Schema names now correctly truncate to 63 characters (PostgreSQL limit)

Release: Bug Fixes and Community Contributions
Version: 2026.8.7.1
Date: February 21, 2026

OVERVIEW

This release includes important bug fixes for schema management, type checking improvements,
dependency updates, and several community-contributed example agents. Focus on stability,
code quality, and expanding the example library.

CHANGES

Bug Fixes:

• Fixed schema name truncation logic for DID-based multi-tenancy
• Fixed type checker error for sys.stdout.reconfigure call
• Fixed docstring formatting to comply with pydocstyle D209
• Stabilized task_manager.py

Features & Enhancements:

• Added paywall example agent demonstrating x402 payment integration
• Added news summarizer agent with local Ollama and DuckDuckGo integration
• Added cybersecurity newsletter agent with security hardening
• Added lightweight in-memory delivery metrics to NotificationService
• Enhanced health endpoint observability
• Added early validation for required author field
• Updated release workflow to use week-based versioning (YYYY.W.D)

Code Quality:

• Added feedback header to sentry.py
• Cleaned up whitespace and formatting across multiple files
• Updated secrets baseline with new line numbers
• Enhanced PR template with comprehensive review checklist
• Removed trailing whitespace and sanitized credentials in documentation

Dependency Updates:

• Updated pydantic: 2.11.3 → 2.12.5 (resolves fastmcp compatibility)
• Updated requests: 2.32.3 → 2.32.5 (resolves langchain-community compatibility)
• Updated sqlalchemy: 2.0.44 → 2.0.46
• Updated tenacity: 8.5.0 → 9.1.4
• Updated rich: 13.9.4 → 14.3.2
• Updated uvx requirement: <2.0 → <4.0

Community:

• Added GitHub Sponsors funding page
• Multiple community contributions merged (PRs #172, #195, #210, #211, #212, #215)

TESTING

✅ All tests passing
✅ Pre-commit hooks passing
✅ Schema truncation test fixed and verified
✅ Type checking errors resolved

CONTRIBUTORS

• Raahul Dutta
• rautsoham03
• ssjgit08
• Krushna
• AseemPrasad
• Sharda2004196
• ssjgit08
• Krushna56

BREAKING CHANGES

None

MIGRATION NOTES

• If upgrading from versions with exact dependency pins, run: uv sync
• Schema names now correctly truncate to 63 characters (PostgreSQL limit)

Release: Code Minimization & Observability Refactor

Version: 2026.8.5
Date: February 19, 2026
Author: Raahul Dutta

OVERVIEW

Major code minimization release focused on removing unused code across the
codebase, particularly in the observability and extensions modules.

BREAKING CHANGES

⚠️ Removed Sentry wrapper functions from public API

• bindu.observability.capture_exception() removed
• bindu.observability.capture_message() removed
• bindu.observability.set_user() removed
• bindu.observability.set_context() removed
• bindu.observability.add_breadcrumb() removed
• bindu.observability.start_transaction() removed

Migration: Use sentry_sdk directly if needed:
from sentry_sdk import capture_exception, set_user, etc.

⚠️ Removed x402 constants file

• bindu/extensions/x402/constants.py deleted
• All constants moved to bindu.settings.X402Settings

Migration: Use app_settings.x402.* instead:
from bindu.settings import app_settings
app_settings.x402.extension_uri
app_settings.x402.meta_status_key
app_settings.x402.status_required

⚠️ Removed internal helper methods

• DIDAgentExtension._sanitize_did_component() (inlined)
• DIDAgentExtension._get_key_paths() (inlined)
• DIDAgentExtension._encode_text() (inlined)

Migration: These were internal methods - no action needed

IMPROVEMENTS

🧹 Observability Module Cleanup (~212 lines removed)

• Removed 6 unused Sentry wrapper functions (176 lines)
• Inlined 3 small helper functions in openinference.py (36 lines)
• Simplified init.py exports (8 exports → 2 exports)
• Kept only production-used functions: setup(), init_sentry()

🔧 X402 Extension Cleanup (~72 lines removed)

• Deleted bindu/extensions/x402/constants.py (31 lines)
• Removed 3 unused utility functions from utils.py (23 lines):
  • build_payment_required_metadata()
  • build_payment_verified_metadata()
  • merge_task_metadata()
• Removed get_agent_extension() from extension.py (18 lines)
• Kept production functions: build_payment_completed_metadata(), build_payment_failed_metadata()

⚡ DID Extension Optimization (~13 lines removed)

• Inlined _get_key_paths() helper method
• Inlined _encode_text() helper method
• Inlined _sanitize_did_component() helper method
• Simplified get_did_document() implementation
• Cleaner, more direct code flow

🧪 Test Suite Cleanup (~232 lines removed)

• Deleted tests/unit/test_x402_constants.py (40 lines)
• Removed unused function tests from test_x402_utils.py (35 lines)
• Removed unused function tests from test_x402_extension.py (11 lines)
• Removed Sentry wrapper tests from test_sentry.py (137 lines)
• Removed _sanitize_did_component test from test_did_extension.py (9 lines)
• All remaining tests passing ✅

🔧 Database Migration Improvements

• Fixed Alembic async migration support
• Auto-converts postgresql:// to postgresql+asyncpg://
• Supports both sync and async PostgreSQL URLs
• Better error handling for driver mismatches

📦 Project Cleanup

• Removed /postman directory (unused API collection)
• Updated .secrets.baseline for code changes
• All pre-commit hooks passing

TECHNICAL DETAILS

Files Modified: 11 files

• bindu/observability/sentry.py (176 lines removed)
• bindu/observability/openinference.py (36 lines removed)
• bindu/observability/init.py (simplified exports)
• bindu/extensions/x402/utils.py (23 lines removed)
• bindu/extensions/x402/extension.py (18 lines removed)
• bindu/extensions/did/did_agent_extension.py (13 lines removed)
• tests/unit/test_sentry.py (137 lines removed)
• tests/unit/test_x402_utils.py (35 lines removed)
• tests/unit/test_x402_extension.py (11 lines removed)
• tests/unit/test_did_extension.py (9 lines removed)
• alembic/env.py (added URL conversion logic)

Files Deleted: 2 files

• bindu/extensions/x402/constants.py
• tests/unit/test_x402_constants.py

Directories Removed: 1 directory

• postman/ (entire directory with API collections)

Code Metrics:
Total Lines Removed: ~590+ lines
Files Modified: 11
Files Deleted: 2
Directories Removed: 1
Production Functionality: 100% preserved
Test Coverage: Maintained
Breaking Changes: 3 (all with migration paths)

Observability Module Changes:
Before: 8 exports (setup, init_sentry, 6 wrapper functions)
After: 2 exports (setup, init_sentry)

Removed Functions (use sentry_sdk directly if needed):
- capture_exception(error, **kwargs)
- capture_message(message, level, **kwargs)
- set_user(user_id, **kwargs)
- set_context(name, data)
- add_breadcrumb(message, category, level, data)
- start_transaction(name, op)

X402 Settings Migration:
Old (constants.py):
from bindu.extensions.x402.constants import X402_EXTENSION_URI
from bindu.extensions.x402.constants import X402Metadata, X402Status

New (settings.py):
from bindu.settings import app_settings
app_settings.x402.extension_uri
app_settings.x402.meta_status_key
app_settings.x402.status_required

TESTING

✅ All unit tests passing
✅ All integration tests passing
✅ Pre-commit hooks passing:

• pytest (66% coverage maintained)
• bandit (security checks)
• detect-secrets (baseline updated)
• pydocstyle (documentation style)
• ruff (linting)
  ✅ No regression in existing functionality
  ✅ Database migrations working correctly

MIGRATION GUIDE

For applications using removed Sentry wrappers:

1. Replace bindu.observability imports:

   Old

   from bindu.observability import capture_exception, set_user

   New

   import sentry_sdk
   sentry_sdk.capture_exception(error)
   sentry_sdk.set_user({"id": user_id})

2. Update x402 constants usage:

   Old

   from bindu.extensions.x402.constants import X402_EXTENSION_URI

   New

   from bindu.settings import app_settings
   uri = app_settings.x402.extension_uri

3. No changes needed for:

   • OpenInference setup (still available)
   • Sentry initialization (still available)
   • DID extension (internal changes only)
   • Database migrations (auto-converts URLs)

For database migrations:

Both formats now work automatically

DATABASE_URL=postgresql://<user_id>:@host/db alembic upgrade head
DATABASE_URL=postgresql+asyncpg://<user_id>:@host/db alembic upgrade head

COMMIT DETAILS

Key Commits:

• 94c850c: refactor: inline helper methods and remove unused Sentry capture functions
• d359497: refactor: remove unused helper methods and inline simple operations in DID and x402 extensions
• c3f0d8f: chore: update secrets baseline with new line number and generation timestamp
• 7faf41e: chore: remove OpenAPI specification file
• 5011f38: chore: ignore postman directory and apply code formatting fixes

Related Pull Requests:

• #152: Add schema manager tests (RachitU)
• #156: Speech-to-text agent example (mandeepsingh2007)
• #179: Require author validation (sakeena-7878)
• #187: Task manager stabilization (chandan-1427)

BENEFITS

✨ Cleaner Codebase

• 590+ lines of unused code removed
• Simpler module interfaces
• Reduced maintenance burden

⚡ Better Performance

• Fewer function calls (inlined helpers)
• Reduced import overhead
• Smaller module footprint

📚 Improved Maintainability

• Less code to understand and maintain
• Clearer separation of concerns
• Better alignment with actual usage

🔒 Enhanced Security

• Fewer unused code paths
• Reduced attack surface
• Updated secrets baseline

USAGE WITH GIT

Create an annotated tag

git tag -a 2026.7.4 -F release-notes/2026.7.4.txt

Create a GitHub release

gh release create 2026.7.4
--notes-file release-notes/2026.7.4.txt
--title "2026.7.4: Code Minimization & Observability Refactor"

View this release

git show 2026.7.4

Push tag to remote

git push origin 2026.7.4

ACKNOWLEDGMENTS

Thanks to all contributors who helped identify unused code and improve
the codebase quality through testing and code reviews.