ResidueOS

ResidueOS is a local AI action gate for real-world agent workflows. It evaluates proposed actions before they execute and returns one stable status:

APPROVE
REVIEW
BLOCK

This MVP is a selective absorption from residueos_mvp.zip, registered in SOURCE_INTAKE_REGISTER.md. It is not a wholesale copy of the ZIP. The original JSON store is replaced with SQLite.

Why It Exists

Modern AI agents can write files, call tools, browse, deploy, spend money, and publish faster than humans can review every step. ResidueOS turns that risk into a small auditable contract: every consequential action needs evidence, authorization, calibration, and a stored decision record.

Problems It Helps With

• Unsafe autonomy: risky actions are stopped at REVIEW or BLOCK.
• Hallucination-to-action drift: claims and actions need evidence before they become irreversible work.
• Lost approvals: human decisions and audit events are stored in SQLite.
• Release risk: public actions, paid APIs, deletion, and publishing can require an authorized receptor.

Receptor Contract

Consequential actions require an authorized receptor. In practice: a request to publish, delete, edit files, run code, approve invoices or send email without receptorId and receptorAuthorized=true returns BLOCK. Low selectivity or low calibration routes the action to review through residue.

Claims Boundary

• This is not a consciousness detector.
• Thresholds and weights are DEMO_ONLY until calibrated with a real dataset.
• Confusion matrices from synthetic examples are DEMO_ONLY.
• Human review is an audit workflow, not a guarantee of safety.

Run

cd residueos
python -m residueos.cli evaluate examples\sample_action.json --db runtime\residueos.sqlite
python -m residueos.cli actions --db runtime\residueos.sqlite
python -m residueos.cli serve --db runtime\residueos.sqlite --port 8787

Then open:

http://127.0.0.1:8787/api/health

API

method	path	purpose
GET	/api/health	health check
POST	/api/evaluate	evaluate and store an action
GET	/api/actions	list stored action records
GET	/api/actions/<id>	fetch one action record
POST	/api/actions/<id>/approve	attach human approval audit
POST	/api/actions/<id>/block	attach human block audit
GET	/api/dashboard	aggregate action stats

Test

python -m unittest discover -s tests

Stored Record

Each SQLite record stores:

• action JSON;
• decision JSON;
• receptor id, authorization and calibration/selectivity metadata;
• optional human decision JSON;
• audit events for evaluation and human review;
• timestamps for creation and update.