ESRA Agents — Universal ESRA Implementation
What is ESRA Agents?
ESRA Agents is the canonical implementation source for five selective ESRA
skills, a dependency-free shared runtime, portable evidence export, and thin
host adapters for chat-scoped and autonomous agents.
It implements the runtime-neutral contracts defined by the
ESRA specification while keeping host names,
paths, lifecycle mappings, permissions, and installation mechanics outside the
portable core.
Routine work bypasses ESRA. Focused skills work independently, and a major
change may receive at most one bounded review.
Current status
- Specification target: ESRA 1.2.
- Portable core: five selective Agent Skills, evidence records, bounded
experiments, audits, and export.
- Autonomous controller: exact-revision promotion, one-time authorization,
blind evaluation, canary rollout, rollback, and privacy-bounded persistence.
- Native adapters: OpenClaw TypeScript adapter at
v0.3.0 prerelease,
Hermes Python plugin; 0.4.0 adds managed discovery and separate Antigravity packaging.
- Maturity boundary: stable autonomous capability remains gated by the
shared host gate and seven-day soak. Package validation and passing tests do
not by themselves prove native lifecycle behavior in every host.
See the autonomous roadmap,
host-gate evidence, and normative
Autonomous Agent Profile
for the exact claim boundaries.
Core components
| Component | Purpose |
|---|
skills/ | Five host-neutral, selectively invoked ESRA skills |
runtime/ | Shared runtime, portable exporter, lifecycle hook, and guarded autonomous controller |
runtime/mcp_evidence.py | Privacy-bounded receipts for GitHub, security, browser-pilot, and SOFA evidence |
adapters/ | Thin host integrations for OpenAI clients, Claude Code, OpenClaw, and Hermes Agent |
docs/ARCHITECTURE.md | Portability boundary, controller policy boundary, and persistence model |
docs/RUNTIME.md | Runtime, export, and autonomous-controller commands |
INSTALL.md | Reproducible installation instructions by host |
esra-conformance.json | Machine-readable implementation capability declaration |
Supported hosts
| Host / surface | Install modes (preferred first) | Stable / edge updates | Hooks | Runtime | Verification |
|---|
| OpenAI / Codex / Desktop | native-marketplace, git, release-zip, local-path | manual-native / manual-native | runtime-dependent | local | isolated native local and tracked Git marketplace/add/list/upgrade/remove; live hooks pending |
| OpenAI / ChatGPT GitHub workspace marketplace | native-marketplace, git | automatic / automatic | runtime-dependent | environment-dependent | official-docs; package-contract-tested; live-integration-pending |
| OpenAI / ChatGPT Work runtime | release-zip, local-path | manual-replace / manual-replace | runtime-dependent | environment-dependent | official-docs; package-contract-tested; live-integration-pending |
| OpenAI / ChatGPT Web / public directory | manual-upload, catalog-submission | manual-replace / manual-replace | none | none | official-docs; package-contract-tested; live-integration-pending |
| OpenAI / Agents API environments | manual-upload, local-path, release-zip | manual-replace / manual-replace | runtime-dependent | environment-dependent | official-docs; package-contract-tested; live-integration-pending |
| Claude / Claude Code | native-marketplace, git, local-path, release-zip | automatic-opt-in / automatic-opt-in | native | local | native strict manifests and isolated tracked Git install/list/update/remove; live hooks pending |
| Claude / Web personal skills | manual-upload | manual-replace / manual-replace | none | none | official-docs; package-contract-tested; live-integration-pending |
| Claude / Team / Enterprise marketplace | native-marketplace, manual-upload | automatic-opt-in / automatic-opt-in | runtime-dependent | environment-dependent | official-docs; package-contract-tested; live-integration-pending |
| Google / Gemini Web skills | manual-upload | manual-replace / manual-replace | none | none | official-docs; package-contract-tested; live-integration-pending |
| xAI / Grok Build / CLI |
Web-only clients receive the portable guidance available to them, not local
Python hooks or filesystem persistence. Use a tagged release and verify
SHA256SUMS before installation. Full commands are in
Installation.
Autonomous loop
The autonomous profile implements:
observation → trigger → proposal → alignment → experiment → blind evaluation → local promotion → canary/rollback
Guarded mode can promote only an exact evaluated revision of a local,
agent-owned, text-only skill. ESRA core, controller and evaluator code, values,
safety rules, credentials, runtime code, host configuration, and canonical
repository content remain human-approved proposals.
Hooks persist only allowlisted metadata and hashes. Prompts, transcripts, tool
arguments and results, secrets, and raw run identifiers are excluded.
Design principles
- One portable core — every supported host uses the same open Agent Skills tree.
- Thin adapters — host-specific manifests, event mappings, paths, and installers stay outside the core.
- Selective invocation — routine work bypasses ESRA and focused skills operate independently.
- Evidence before promotion — experiments require explicit alignment, evaluation, authorization, and rollback.
- Privacy by construction — lifecycle hooks retain only allowlisted metadata and hashes.
- Bounded autonomy — protected surfaces remain human-approved and native mutation uses a separate authorized identity.
How to use this repository
- Read Architecture for the portable-core and host-adapter boundary.
- Choose a host and follow Installation using a tagged release.
- Use the focused skill that matches the task; do not load the full catalog for routine work.
- Use Runtime commands for evidence export or guarded controller operations.
- Complete the host gate before making native autonomous-capability claims.
Development
Run the repository checks from the project root:
.venv/bin/python scripts/validate_skills.py
.venv/bin/python scripts/validate_plugin.py
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/build_distributions.py
.venv/bin/python scripts/validate_distributions.py
Relationship to ESRA
The esra repository defines what the
architecture is: its specification, data contracts, conformance tests, and
host-pilot gates.
This repository defines the canonical cross-host implementation: portable
skills and runtime behavior with thin host adapters.
Earlier host-specific repositories remain available during migration and retain
their existing release URLs:
License
Apache-2.0 — see LICENSE. Attribution and trademark separation are
recorded in NOTICE.
ESRA Agents is a living implementation.
It evolves together with the ESRA specification and its host evidence.
