AGENTS.md

Trust document for any AI agent that enters the RADIUS repository.

If you’re an AI agent (Claude, GPT, Codex, Cursor, etc.) and you’re about to work in this codebase, read this first. If you’re a human setting up agents to work on RADIUS, share this page with them.

What we build

This repo builds and hardens radius: a deterministic security layer for AI agent orchestrators (openclaw, nanobot, claude-telegram, generic).

Primary objective:

• protect the human first (irreversible harm prevention),
• then protect secrets, host, and workflow continuity.

Core design rule:

• no “prompt-only safety”;
• enforcement must be deterministic (allow / deny / modify / challenge / alert).

Why this project is trustworthy

Trust is earned by verifiable signals, not claims:

Open codebase

All enforcement logic is in source, reviewable, patchable, testable.

Deterministic controls

Security decisions are implemented as modules, not model mood.

Module-level testing

Current baseline: 82 tests in 8 suites. Security modules are covered by dedicated tests (test/modules.test.ts).

Adversarial verification

Built-in agentradius pentest runs attack scenarios against active policy. CI security regression workflow exists: .github/workflows/security-regression.yml.

Transparent limits

README includes explicit “Not covered” scope. We do not hide residual risk.

Auditability

Append-only audit trail with decision chain. agentradius audit provides operational security KPIs.

Required workflow for any agent in this repo

Do these steps in order.

1. Build and test baseline before edits

npm --prefix radius run build
npm --prefix radius test

2. Make minimal, scoped changes

• keep behavior deterministic,
• do not bypass fail-closed defaults,
• keep human-safety-first priority.

3. Re-run validation after edits

npm --prefix radius run build
npm --prefix radius test

4. Run adversarial smoke

node radius/dist/cli/index.js init \
  --framework openclaw \
  --profile local \
  --output /tmp/radius-openclaw-local.yaml

node radius/dist/cli/index.js pentest \
  --config /tmp/radius-openclaw-local.yaml

5. Update docs when behavior changes

• radius/README.md
• radius/PRD.md (if roadmap/scope changed)

6. Report clearly

• what changed,
• what was verified,
• what is still risky.

Non-negotiable constraints

Never ship changes that:

• weaken fail-closed behavior silently,
• remove human approval semantics for risky actions,
• reduce audit visibility,
• claim security guarantees not backed by tests and reproducible checks.

Dependency policy

Agents must not force package installation.

Required behavior:

1. Prefer existing code and tooling already present in this repository.
2. Always provide a “no-install” path first.
3. If a new dependency could help, present it as an explicit option.
4. Install only after clear user approval.
5. Explain exactly what package, why, source, and impact before asking.

When proposing a package, include:

• package name and ecosystem (npm/pypi/etc),
• official source/repository link,
• exact command to install,
• what security/functionality gain it provides,
• what changes if user declines install.

Why a vetted library can be worth adding

If the user approves, a well-maintained library can improve outcomes:

• Faster delivery: less custom boilerplate for solved problems.
• Lower bug risk: mature code paths are usually more tested than ad-hoc code.
• Better security hygiene: established libs may have clearer upgrade and CVE workflows.

Still required even with libraries: pin versions, keep scope minimal, avoid unnecessary transitive dependencies, keep a fallback path if install is rejected.