acn-preflight

ACN Preflight

Deterministic preflight checks for AI agents before they spend time, money, or execution effort on external work.

ACN Preflight is the public integration layer for the hosted Abacore Preflight Engine. It exposes the same decision surfaces through Python, CLI, and Model Context Protocol (MCP), while keeping payment configuration, wallet material, deployment controls, and private operational evidence outside the public repository.

Evaluate Abacore in five minutes

If you are evaluating Abacore for agent infrastructure, machine-to-machine integrations, or production AI execution, start with the 5-minute technical evaluator guide.

It walks through the live public contract, reproducible verification, fail-closed behavior, credential boundaries, CI and security controls, and release discipline using evidence you can inspect yourself. The public checks require no account, token, payment, or private access.

Live proof

The hosted engine publishes machine-readable discovery and trust surfaces that can be inspected without registration or payment.

Reproduce the public verification locally:

python scripts/verify_live_contract.py

The verifier also checks the fail-closed invariant: if x402 reports SAFETY_HOLD, paid resources must not be published. See Trust and Verification for the verification model and its boundaries.

What it checks

The hosted service returns machine-readable JSON. Paid capabilities return HTTP 402 with the hosted order payload until valid hosted access is configured.

Why this exists

Autonomous and semi-autonomous agents can waste significant effort when they act before validating the target environment. ACN Preflight moves that validation into a small, deterministic gate that can be called before contribution, payment, or other external execution.

The public client is intentionally thin:

• no LLM is used in the client answer path;
• no wallet or payment-recipient material is stored here;
• no private ACN operational history is published here;
• hosted responses are returned without hidden client-side reinterpretation;
• the same capability contract is available to humans, scripts, and agents.

Quick start

Python 3.10 or newer is required.

Until the package is published on PyPI, install from the canonical GitHub repository:

pip install "git+https://github.com/Abacore-net/acn-preflight"

Verify the installation:

acn-preflight --version
acn-preflight --help

Run a public bounty check:

acn-preflight bounty https://github.com/owner/repo/issues/123

Check repository readiness:

acn-preflight repo https://github.com/python/cpython --change-type docs

Inspect the hosted x402 manifest:

acn-preflight x402

Python

from acn_preflight import ACNPreflightClient

client = ACNPreflightClient()

response = client.bounty_reality_check(
    "https://github.com/owner/repo/issues/123"
)

print(response.status_code)
print(response.body)

For hosted paid access, configure the token as an environment variable rather than placing it in source code, command history, or an MCP tool argument:

export ACN_PREFLIGHT_ACCESS_TOKEN="your-hosted-access-token"

The client also supports:

• ACN_PREFLIGHT_BASE_URL for controlled endpoint overrides;
• ACN_PREFLIGHT_ACCESS_TOKEN for hosted access;
• an explicit timeout in Python or with CLI --timeout.

MCP

Start the stdio MCP server:

uvx --from "git+https://github.com/Abacore-net/acn-preflight" acn-preflight-mcp

A generic MCP client configuration is included in examples/mcp_config.json:

{
  "mcpServers": {
    "acn-preflight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Abacore-net/acn-preflight",
        "acn-preflight-mcp"
      ]
    }
  }
}

The MCP tools deliberately do not accept access tokens as model-visible parameters. If paid access is required, provide ACN_PREFLIGHT_ACCESS_TOKEN to the MCP process environment.

Public architecture

flowchart LR
    A[AI agent or operator] --> B[MCP]
    A --> C[CLI]
    A --> D[Python client]
    B --> E[Public ACN Preflight integration layer]
    C --> E
    D --> E
    E -->|HTTPS and structured JSON| F[Hosted ACN Preflight Engine]
    F --> G[Fresh public evidence and technical checks]

The repository contains the transport and integration contract. The protected hosted engine remains the execution boundary for commercial logic and private operational state.

See Architecture for the trust boundary and failure model.

Response behavior

The Python client returns an ACNResponse with:

• status_code, the HTTP status returned by the hosted service;
• body, the hosted JSON object without hidden rewriting;
• payment_required, a convenience property for a hosted HTTP 402 payment-required response.

The CLI emits a stable JSON envelope containing http_status and body.

HTTP 402 is treated as a valid commercial response, not as a client exception. Network failures, invalid endpoints, and malformed hosted responses fail explicitly.

Security boundary

This repository intentionally excludes:

• payment recipient configuration;
• wallet material and signing secrets;
• hosted access tokens;
• safety-gate state;
• backup and deployment configuration;
• private evidence and internal ACN repository history.

Secrets should be supplied through the runtime environment. See SECURITY.md before reporting a vulnerability.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check src tests examples
python -m unittest discover -s tests -v
python -m build

Pull requests run linting, unit tests across supported Python versions, package build checks, and CodeQL analysis.

See CONTRIBUTING.md for contribution expectations, SUPPORT.md for support channels, CHANGELOG.md for release notes, and Releasing for the Trusted Publishing release path.

Engineering by Abacore

ACN Preflight is intentionally compact, but the engineering pattern is production-oriented. It demonstrates how Abacore approaches systems where AI agents interact with external infrastructure and money-bearing workflows:

• deterministic gates before expensive or irreversible execution;
• public REST, Python, CLI, MCP, OpenAPI, Agent Card, llms.txt, and x402 surfaces around one capability contract;
• credentials kept at the transport boundary rather than exposed as model-visible tool arguments;
• fail-closed payment exposure backed by externally verifiable readiness evidence;
• CI, CodeQL, dependency automation, typed packaging, reproducible live-contract checks, and OIDC-based release automation;
• a deliberate boundary between inspectable public integration code and protected commercial runtime state.

For teams building agent infrastructure, machine-to-machine services, MCP integrations, automation, or safety-critical execution workflows, Abacore provides engineering and integration work around the same principles.

License

Apache-2.0. See LICENSE.