ESRA Agents — Universal ESRA Implementation

Validate License: Apache-2.0 Specification: ESRA 1.2 Release: v0.3.0 prerelease

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	git, native-marketplace, local-path, release-zip	manual-native / manual-native	native	local	native validate and isolated tracked Git install/discovery/update/remove; five skills and hooks discovered; live dispatch pending
xAI / Grok Web / Bot instructions	manual-upload	manual-replace / manual-replace	none	none	file guidance only; persistent Bot skills and ZIP import unverified
Hermes / Agent / Desktop	git, local-path, release-zip, catalog-submission	manual-native / automatic-opt-in	native	local	native root/archive validation and registration; managed install/update/pin skipped: host package manager missing uv.lock
OpenClaw / Gateway / CLI	git, local-path, release-zip, tarball, npm, catalog-submission	manual-native / manual-native	native	local	official-docs; package-contract-tested; live-integration-pending
Google / Antigravity CLI / IDE / 2.0 custom	local-path, release-zip	manual-replace / manual-replace	native	local	official-docs; package-contract-tested; live-integration-pending
Agent Skills / Generic consumers	manual-upload, local-path, git	manual-replace / manual-replace	none	none	official-docs; package-contract-tested; live-integration-pending

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:

hermes-esra — legacy Hermes skills and integration toolkit
chatgpt-esra — legacy OpenAI distribution for ChatGPT and Codex
claude-esra — legacy Claude Code distribution

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.