solystopia-agent-preflight 0.1.0__tar.gz

solystopia_agent_preflight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Silas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

solystopia_agent_preflight-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: solystopia-agent-preflight
+Version: 0.1.0
+Summary: Deterministic pre-deployment checks for AI agent systems. Blocks unsafe designs before they ship.
+Author-email: Arthur Silas <arthur-silas@agentmail.to>
+License: MIT
+Project-URL: Homepage, https://github.com/arthursilas-ai/agent-preflight
+Project-URL: Repository, https://github.com/arthursilas-ai/agent-preflight
+Project-URL: Changelog, https://github.com/arthursilas-ai/agent-preflight/blob/main/CHANGELOG.md
+Keywords: ai-agents,ai-safety,ci-cd,deployment,preflight
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+![agent-preflight](assets/banner.svg)
+
+# agent-preflight
+
+**Deterministic pre-deployment checks for AI agent systems.**
+
+[![ci](https://github.com/arthursilas-ai/agent-preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/arthursilas-ai/agent-preflight/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+
+Your agent works in the demo. Will it pass review?
+
+## Install
+
+As an agent skill (works in Claude Code, Cursor, Copilot, Codex, Gemini, Zed and others):
+
+```bash
+npx skills add arthursilas-ai/agent-preflight
+```
+
+As a CLI, straight from GitHub — no PyPI account needed, no repo to clone:
+
+```bash
+pip install git+https://github.com/arthursilas-ai/agent-preflight.git
+agent-preflight --init                 # write a starter spec
+agent-preflight agent-spec.yaml        # check it
+agent-preflight --explain ops.liveness # why a check exists
+```
+
+Or standalone — one file, no install, no account:
+
+```bash
+curl -O https://raw.githubusercontent.com/arthursilas-ai/agent-preflight/main/scripts/preflight.py
+pip install pyyaml
+
+python3 preflight.py --init                 # write a starter spec
+python3 preflight.py agent-spec.yaml        # check it
+python3 preflight.py --explain ops.liveness # why a check exists
+```
+
+Exit codes: `0` passed · `1` blocked · `2` spec unreadable. Add `--json` for
+CI, `--strict` to fail on warnings too.
+
+---
+
+## Why
+
+Around **88% of enterprise agent pilots never reach production**. The
+reported blockers are evaluation gaps, governance friction and reliability —
+not model quality.
+
+There are excellent tools for watching an agent at runtime. There is very
+little for the question that actually stalls a pilot:
+
+> *Is this safe to ship, and can I show someone why?*
+
+`agent-preflight` answers that with a deterministic verdict. No model calls,
+no network, no vendor. The same spec always yields the same result, which is
+what makes it reviewable — and what makes it usable in CI.
+
+New here? [**Walkthrough: from blank spec to shippable**](docs/walkthrough.md) — a real pass over a small agent, about ten minutes.
+
+Second example, different failure profile: [**a research agent**](docs/research-agent.md) that reads untrusted content but never touches money.
+
+## What it catches
+
+Run against a realistic refunds agent that demos perfectly:
+
+```
+BLOCKING (22)
+  x [tenancy.rls]        Multi-tenant system without row-level security.
+  x [credentials.exposure] Privileged credentials are not restricted to server-side only.
+  x [injection.gating]   Consequential actions are reachable from untrusted content.
+  x [tool.approval]      Tool issue_refund: irreversible tool without an approval gate.
+  x [tool.idempotency]   Tool issue_refund: irreversible tool has no idempotency strategy.
+  x [agent.step_limit]   Agent refund_agent: no step_limit.
+  x [ops.liveness]       Scheduled system has no liveness alert for a run that never happens.
+  ...
+
+VERDICT: BLOCKED — do not deploy until the above are resolved.
+```
+
+Every finding carries a fix, not just a complaint.
+
+
+## Use it in CI
+
+```yaml
+- uses: arthursilas-ai/agent-preflight@main
+  with:
+    spec: agent-spec.yaml
+    strict: "false"
+```
+
+Fails the build on blocking findings, writes them to the job summary, and
+comments on the pull request. Outputs `passed` and `blocking-count` if you
+want to gate a deploy step on them.
+
+## The check areas
+
+Purpose · Architecture shape · Tenancy isolation · Credential exposure ·
+Prompt-injection gating · Tool contracts (idempotency, approval, scope) ·
+Agent bounds (step limit, cost budget, stop conditions) · Evaluation
+(including adversarial cases) · Operations (logging, alerting, rollback) ·
+Liveness · Billing and fulfilment.
+
+Full rationale and threat model: [references/checks.md](references/checks.md).
+
+## One check that exists because it bit us
+
+```
+x [ops.liveness] Scheduled system has no liveness alert for a run that never happens.
+```
+
+We built an agent with scheduled daily routines. The jobs were declared
+correctly and registered correctly on the platform. They simply never fired
+— for two days — and nothing alerted, because *nothing had gone wrong*.
+There were no errors to catch. The absence of runs looked exactly like a
+quiet day.
+
+We only found it by querying the database and noticing that every event had
+come from a manual test.
+
+Most agent outages are not crashes. They are things that quietly stopped
+happening. If your monitoring only watches for errors, it cannot see this
+class of failure at all.
+
+## Honest limits
+
+This validates **declared design**, not running behaviour.
+
+A passing verdict means the stated design contains no known unsafe patterns.
+It is **evidence for a human reviewer** — not a guarantee, not a security
+certification, and not a compliance attestation. A spec that lies still
+passes. It complements runtime observability; it does not replace it.
+
+## Contributing
+
+New checks are welcome, with one requirement: a check must encode a failure
+that has actually happened to someone, and must ship with a fix line telling
+the reader what to do. Speculative checks make the tool noisy and get it
+ignored.
+
+## Licence
+
+MIT © [Arthur](https://github.com/arthursilas-ai)

solystopia_agent_preflight-0.1.0/README.md

@@ -0,0 +1,146 @@
+![agent-preflight](assets/banner.svg)
+
+# agent-preflight
+
+**Deterministic pre-deployment checks for AI agent systems.**
+
+[![ci](https://github.com/arthursilas-ai/agent-preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/arthursilas-ai/agent-preflight/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+
+Your agent works in the demo. Will it pass review?
+
+## Install
+
+As an agent skill (works in Claude Code, Cursor, Copilot, Codex, Gemini, Zed and others):
+
+```bash
+npx skills add arthursilas-ai/agent-preflight
+```
+
+As a CLI, straight from GitHub — no PyPI account needed, no repo to clone:
+
+```bash
+pip install git+https://github.com/arthursilas-ai/agent-preflight.git
+agent-preflight --init                 # write a starter spec
+agent-preflight agent-spec.yaml        # check it
+agent-preflight --explain ops.liveness # why a check exists
+```
+
+Or standalone — one file, no install, no account:
+
+```bash
+curl -O https://raw.githubusercontent.com/arthursilas-ai/agent-preflight/main/scripts/preflight.py
+pip install pyyaml
+
+python3 preflight.py --init                 # write a starter spec
+python3 preflight.py agent-spec.yaml        # check it
+python3 preflight.py --explain ops.liveness # why a check exists
+```
+
+Exit codes: `0` passed · `1` blocked · `2` spec unreadable. Add `--json` for
+CI, `--strict` to fail on warnings too.
+
+---
+
+## Why
+
+Around **88% of enterprise agent pilots never reach production**. The
+reported blockers are evaluation gaps, governance friction and reliability —
+not model quality.
+
+There are excellent tools for watching an agent at runtime. There is very
+little for the question that actually stalls a pilot:
+
+> *Is this safe to ship, and can I show someone why?*
+
+`agent-preflight` answers that with a deterministic verdict. No model calls,
+no network, no vendor. The same spec always yields the same result, which is
+what makes it reviewable — and what makes it usable in CI.
+
+New here? [**Walkthrough: from blank spec to shippable**](docs/walkthrough.md) — a real pass over a small agent, about ten minutes.
+
+Second example, different failure profile: [**a research agent**](docs/research-agent.md) that reads untrusted content but never touches money.
+
+## What it catches
+
+Run against a realistic refunds agent that demos perfectly:
+
+```
+BLOCKING (22)
+  x [tenancy.rls]        Multi-tenant system without row-level security.
+  x [credentials.exposure] Privileged credentials are not restricted to server-side only.
+  x [injection.gating]   Consequential actions are reachable from untrusted content.
+  x [tool.approval]      Tool issue_refund: irreversible tool without an approval gate.
+  x [tool.idempotency]   Tool issue_refund: irreversible tool has no idempotency strategy.
+  x [agent.step_limit]   Agent refund_agent: no step_limit.
+  x [ops.liveness]       Scheduled system has no liveness alert for a run that never happens.
+  ...
+
+VERDICT: BLOCKED — do not deploy until the above are resolved.
+```
+
+Every finding carries a fix, not just a complaint.
+
+
+## Use it in CI
+
+```yaml
+- uses: arthursilas-ai/agent-preflight@main
+  with:
+    spec: agent-spec.yaml
+    strict: "false"
+```
+
+Fails the build on blocking findings, writes them to the job summary, and
+comments on the pull request. Outputs `passed` and `blocking-count` if you
+want to gate a deploy step on them.
+
+## The check areas
+
+Purpose · Architecture shape · Tenancy isolation · Credential exposure ·
+Prompt-injection gating · Tool contracts (idempotency, approval, scope) ·
+Agent bounds (step limit, cost budget, stop conditions) · Evaluation
+(including adversarial cases) · Operations (logging, alerting, rollback) ·
+Liveness · Billing and fulfilment.
+
+Full rationale and threat model: [references/checks.md](references/checks.md).
+
+## One check that exists because it bit us
+
+```
+x [ops.liveness] Scheduled system has no liveness alert for a run that never happens.
+```
+
+We built an agent with scheduled daily routines. The jobs were declared
+correctly and registered correctly on the platform. They simply never fired
+— for two days — and nothing alerted, because *nothing had gone wrong*.
+There were no errors to catch. The absence of runs looked exactly like a
+quiet day.
+
+We only found it by querying the database and noticing that every event had
+come from a manual test.
+
+Most agent outages are not crashes. They are things that quietly stopped
+happening. If your monitoring only watches for errors, it cannot see this
+class of failure at all.
+
+## Honest limits
+
+This validates **declared design**, not running behaviour.
+
+A passing verdict means the stated design contains no known unsafe patterns.
+It is **evidence for a human reviewer** — not a guarantee, not a security
+certification, and not a compliance attestation. A spec that lies still
+passes. It complements runtime observability; it does not replace it.
+
+## Contributing
+
+New checks are welcome, with one requirement: a check must encode a failure
+that has actually happened to someone, and must ship with a fix line telling
+the reader what to do. Speculative checks make the tool noisy and get it
+ignored.
+
+## Licence
+
+MIT © [Arthur](https://github.com/arthursilas-ai)

solystopia_agent_preflight-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "solystopia-agent-preflight"
+version = "0.1.0"
+description = "Deterministic pre-deployment checks for AI agent systems. Blocks unsafe designs before they ship."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["pyyaml>=6.0"]
+license = { text = "MIT" }
+authors = [{ name = "Arthur Silas", email = "arthur-silas@agentmail.to" }]
+keywords = ["ai-agents", "ai-safety", "ci-cd", "deployment", "preflight"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/arthursilas-ai/agent-preflight"
+Repository = "https://github.com/arthursilas-ai/agent-preflight"
+Changelog = "https://github.com/arthursilas-ai/agent-preflight/blob/main/CHANGELOG.md"
+
+# The distribution name is prefixed solystopia- because "agent-preflight" is
+# already taken on PyPI by an unrelated project. The installed command stays
+# short — `agent-preflight` — since command names don't need to be globally
+# unique the way distribution names do.
+[project.scripts]
+agent-preflight = "preflight:cli"
+
+[tool.setuptools]
+py-modules = ["preflight"]
+
+[tool.setuptools.package-dir]
+"" = "scripts"