ARCHMAGE

saeng-il ai [ research | development | integration ]

Deterministic pre-execution control for coding-agent actions.

Current release: v2.0.0. Python distributions are published as archmage-ai; the portable Agent Plugin is attached separately to the GitHub release.

ARCHMAGE evaluates a proposed tool action before an adapter dispatches it. The runtime converts the proposal into a stable digest, runs deterministic policy evaluators, and emits one typed decision:

ALLOW · ALLOW_WITH_OBLIGATIONS · REPAIR · DENY · ESCALATE

It is designed for coding-agent file writes, command proposals, protected-policy changes, declared scope, artifact lineage, identity, and evidence obligations.

Two-minute example

from dataclasses import replace

from archmage import (
    ActionProposal,
    ActorIdentity,
    PolicyContext,
    create_default_policy_decision_point,
)

pdp = create_default_policy_decision_point()
context = PolicyContext(
    workspace="/workspace/project",
    environment="local",
    audit_logger_configured=True,
)
proposal = ActionProposal(
    task_id="task-42",
    actor=ActorIdentity(actor_id="coding-agent", actor_type="agent"),
    operation="write_file",
    tool="write_to_file",
    arguments={"TargetFile": "../outside.py"},
    target_paths=["../outside.py"],
    requested_side_effects=[],
    repository_revision="0123456789abcdef0123456789abcdef01234567",
    environment="local",
)

blocked = pdp.evaluate(proposal, context)
print(blocked.decision)  # VerdictDecision.DENY

narrowed = replace(
    proposal,
    arguments={"TargetFile": "src/feature.py"},
    target_paths=["src/feature.py"],
)
allowed = pdp.evaluate(narrowed, context)
print(allowed.decision)  # VerdictDecision.ALLOW

The adapter or executor must refuse dispatch unless the returned decision permits it. ARCHMAGE does not independently intercept arbitrary operating-system activity.

Install and verify

Install the signed package release:

python -m pip install archmage-ai

For development from a reviewed checkout:

python -m pip install --editable ".[dev]"
python -m pytest

Release wheels and source distributions are built in GitHub Actions, accompanied by SHA-256 checksums, an SPDX SBOM, and GitHub artifact attestations. Verification instructions are in the supply-chain guide.

Agent Plugin

ARCHMAGE also ships a separate, self-contained Agent Plugins 1.0.0 ZIP. The plugin is an interoperability and distribution adapter: its Agent Skill tells a compatible host when to invoke the bundled MCP tools, while those tools route every decision through the same Python PolicyEnforcementPoint used by native integrations.

The ZIP is deliberately separate from the wheel and source distribution. It is validated against vendored Agent Plugins schemas, smoke-tested directly from an extracted archive, and never submitted to PyPI or Python metadata validation. See the Agent Plugin guide for the trust boundary and installation sequence.

What is included

• Eleven deterministic core evaluators with fail-closed aggregation.
• A generic tool-call adapter with explicit identity, workspace, and immutable revision requirements and canonical JSON payload validation.
• A reference Antigravity adapter.
• Digest-bound, verifier-backed, single-use approval records for destructive and shell-command obligations.
• Contract evaluators for interface depth and contract-first Python changes.
• Reproducible gold-case, repair-loop, policy-drift, and latency benchmarks.
• An Apache-2.0 licensed skill and doctrine bundle.
• A portable Agent Plugins 1.0.0 edge adapter with durable JSONL audit records.

Validated release-candidate benchmarks

The latest hosted candidate evidence is produced by the revision-bound CI workflow. Every JSON artifact records the exact commit, case catalog, Python version, and runner platform. Signed release artifacts will supersede this release-candidate snapshot.

These are deterministic proposal-level results from one recorded environment, not claims of universal agent safety or platform-wide performance. See the benchmark guide and security claims policy.

Security boundary

ARCHMAGE is a policy decision and enforcement library, not a sandbox, firewall, credential vault, malware scanner, or complete prompt-injection defense. Its guarantees depend on every relevant tool call passing through a correctly wired adapter, on the host preventing bypass around that adapter, and on the host authenticating any approval record before its verifier accepts it.

Read limitations before integrating it with privileged tools. Report suspected vulnerabilities through the private route documented in SECURITY.md once that release-gate policy is approved.

Documentation

• Published documentation
• Quickstart
• Core concepts
• Policy model
• Architecture
• Agent Plugin
• Adapters
• Writing custom evaluators
• Benchmarks
• Security claims
• Threat model
• Limitations
• Supply-chain verification

Contributing

Contribution access is approval-only. Start with a proposal and read CONTRIBUTING.md and ARCHMAGE_RANKS.md. Security-sensitive changes require private disclosure and tests that demonstrate both the blocked path and the expected compliant path.

License

Apache License 2.0. See LICENSE.