agent-runtime-pattern

A dependency-zero reference pattern for durable AI-agent runtimes: append-only event logs, logical event lanes, authority-gated transitions, validation-before-action, heartbeat/liveness, replayable state, and proof artifacts.

This repository uses only synthetic examples. It contains no client code, private schemas, credentials, deployment details, private integrations, or live operational data.

Why This Exists

Most agent demos show the happy path: a model decides, a tool runs, and the UI says done.

This repo focuses on the control boundary instead:

• observation is not permission,
• acknowledgement is not permission,
• recommendation is not permission,
• approval is scoped to one exact preview,
• execution is blocked when liveness is stale,
• completion requires proof.

Supply Chain Posture

This repo intentionally has no third-party dependencies.

Do not run package-manager install commands to use it. The local verification path uses the already-present Node.js runtime and built-in modules only.

node scripts/verify-public-ready.js

See:

• SECURITY_PREFLIGHT.md
• SECURITY.md
• docs/supply-chain-policy.md
• docs/download-decision-log.md
• docs/release-checklist.md

Runtime Flow

observed
  -> researched
  -> recommended
  -> previewed
  -> approval_requested
     -> acknowledged (optional control event, no authority)
     -> approved -> executed_stub -> reconciled -> proof_written
     -> rejected -> proof_written

What The Tests Prove

• Valid flow reaches proof_written.
• Execution before approval fails.
• Acknowledgement before approval does not authorize execution.
• Approval for one preview cannot execute a different preview.
• Stale heartbeat blocks execution.
• Rejected preview cannot execute.
• A replacement preview after rejection requires a new approval.
• Event timestamps cannot move backwards.
• Event lanes separate control, authority, action, and proof.
• Replay reconstructs final state.
• Completion without proof fails.
• Post-completion acknowledgement fails.

What This Demonstrates

The fixture is intentionally small, but the pattern maps to larger agent infrastructure concerns:

• stateful workflows for long-running agent tasks,
• control-plane events separated from action authority,
• replayable state for debugging and evaluation,
• liveness checks before consequential execution,
• clean boundaries between recommendation, approval, action, reconciliation, and proof,
• local verification without expanding supply-chain risk.

Files To Read First

• docs/architecture.md
• docs/reviewer-guide.md
• docs/lane-model.md
• docs/authority-ladder.md
• docs/operating-envelope.md
• docs/workorder-template.md
• docs/evidence-checklist.md
• examples/toy_support_triage/sample-proof.md
• CHANGELOG.md

Run It

node --test
node scripts/generate-sample-proof.js
node scripts/verify-public-ready.js

These commands use Node built-ins only. They do not install packages, contact registries, call APIs, or run live integrations.

What This Deliberately Omits

• Live tool calls.
• API keys.
• Registry dependencies.
• CI workflows.
• Browser extensions.
• Containers.
• Private system details.

The point is not to make an impressive app shell. The point is to show a small, inspectable runtime boundary that refuses unsafe action.