From f07c630ee1f105aaf8f0d6d53aaad2cc71eb64f0 Mon Sep 17 00:00:00 2001 From: ditdit Date: Mon, 3 Aug 2026 18:02:01 -0700 Subject: [PATCH] Clarify product positioning hierarchy (#73) --- README.md | 50 ++++++----- docs/action-gate-roadmap.md | 29 ++++++- docs/interoperability-positioning.md | 6 +- docs/positioning.md | 125 +++++++++++++++++++++++++++ docs/standards-alignment.md | 11 +-- pyproject.toml | 2 +- tests/test_positioning_docs.py | 101 ++++++++++++++++++++++ 7 files changed, 288 insertions(+), 36 deletions(-) create mode 100644 docs/positioning.md create mode 100644 tests/test_positioning_docs.py diff --git a/README.md b/README.md index ff3be59..c48f195 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,24 @@ # AgentPass -**Open interoperability and conformance for action-bound AI agent authorization.** +**Action authorization and execution assurance for AI agents.** -AgentPass is an open reference implementation, action-control boundary, and -conformance project that sits outside the agent loop. It checks tool calls -before execution and preserves durable records of what was proposed, -authorized, executed, observed, and assessed. +AgentPass is an action-control and evidence layer that sits outside the agent +loop. It decides whether a specific tool call may execute and preserves durable +records of what was proposed, authorized, executed, observed, and assessed. -Its standards role is deliberately narrow: compose existing identity, -delegation, workload, policy, and signing standards into independently -verifiable evidence for a specific agent action. AgentPass does not define a -general agent identity or replace IAM, OAuth, MCP authorization, AuthZEN, -SPIFFE, WIMSE, OPA, Cedar, or provider business authorization. See -[Interoperability Positioning](docs/interoperability-positioning.md). +> AgentPass controls consequential AI agent actions and produces independently +> verifiable evidence of what was authorized and executed. ```text Agent proposes tool call -> AgentPass checks policy + state -> allow / deny / challenge ``` +Identity, workload, and policy systems provide inputs to that decision. +AgentPass composes them at the action boundary and adds stateful enforcement, +provider-verifiable authorization evidence, and execution assurance. Its open +conformance work demonstrates interoperability; it is not the product category. +See [Project Positioning](docs/positioning.md). + The runtime decision remains the core enforcement point. The current implementation also includes versioned intent contracts, execution evidence, verified outcome observations, immutable evidence snapshots and final @@ -390,19 +391,20 @@ AgentPass currently includes: ## Roadmap Focus -Near-term work has four public tracks: - -1. Action-bound authorization interoperability: executable MCP conformance - cases, provider-verifier behavior, negative fixtures, implementation - profiles, and demonstrations with independent implementations. -2. Production-grade intent observability and assurance: canonical evidence - contracts, action-boundary lifecycle hardening, OpenTelemetry causal - tracing, correlation, measurement profiles, independent control assessment, - complete population accounting, immutable assessment revisions, privacy, - migration, and conformance. -3. Provider trust enforcement with production receipts and contract drift - detection. -4. Framework and workflow wrappers selected from adopter demand. +Near-term work follows three product layers: + +1. **Runtime authorization and control:** policy enforcement, approvals, + budgets, data-flow controls, idempotency, replay protection, and integrations + at agent, workflow, gateway, and provider boundaries. +2. **Portable provider trust and interoperability:** signed action-bound + evidence, independent provider verification, contract drift detection, + conformance cases, profiles, and multi-implementation demonstrations. +3. **Execution and outcome assurance:** linked execution receipts, immutable + evidence, verified observations, causal traces, intent evaluation, and + comparable assurance metrics. + +Framework wrappers and conformance suites are delivery mechanisms within these +layers, not separate product categories. The [Action Gate Roadmap](docs/action-gate-roadmap.md) tracks adopter-facing product demonstrations. The public diff --git a/docs/action-gate-roadmap.md b/docs/action-gate-roadmap.md index ed254f3..633fe06 100644 --- a/docs/action-gate-roadmap.md +++ b/docs/action-gate-roadmap.md @@ -4,9 +4,12 @@ This roadmap documents the near-term product direction for AgentPass. The positioning target is: -> AgentPass is the runtime action gate for AI agents before they call tools, -> send messages, move money, update records, deploy code, or touch sensitive -> data. +> AgentPass controls consequential AI agent actions and produces independently +> verifiable evidence of what was authorized and executed. + +The action gate is the core product boundary inside the broader category of +action authorization and execution assurance. The canonical message hierarchy +is in [Project Positioning](positioning.md). The developer problem is not only agent identity. Builders already have agents, tools, API keys, MCP servers, workflow engines, and model calls. What they lack @@ -67,7 +70,25 @@ agent loop. The stronger product story is: Recommended public line: -> AgentPass is a runtime guard for AI agent tool calls. +> AgentPass is an action authorization guard for AI agent tool calls. + +## Three-Layer Product Roadmap + +The roadmap uses the same three product layers as the README and canonical +positioning: + +1. **Runtime authorization and control:** stop unsafe, unauthorized, duplicate, + or unapproved actions at the execution boundary. +2. **Portable provider trust and interoperability:** let downstream providers + independently verify action-bound authorization evidence across trust + boundaries. +3. **Execution and outcome assurance:** link authorization to execution, + independently observed outcomes, and durable assessment evidence. + +Framework wrappers distribute the runtime boundary. Conformance suites test +portable provider trust. Observability supplies operational context for +assurance. They advance these layers rather than forming separate product +categories. ## Roadmap diff --git a/docs/interoperability-positioning.md b/docs/interoperability-positioning.md index eb052bb..cfacb24 100644 --- a/docs/interoperability-positioning.md +++ b/docs/interoperability-positioning.md @@ -1,7 +1,9 @@ # AgentPass Interoperability Positioning -AgentPass is an open reference implementation and conformance project for -action-bound authorization of AI agent operations. +Interoperability and conformance are the open ecosystem strategy for +AgentPass's broader product category: action authorization and execution +assurance for AI agents. The canonical product hierarchy is defined in +[Project Positioning](positioning.md). Its focus is the provider trust boundary: diff --git a/docs/positioning.md b/docs/positioning.md new file mode 100644 index 0000000..5ebfa28 --- /dev/null +++ b/docs/positioning.md @@ -0,0 +1,125 @@ +# AgentPass Project Positioning + +## Category + +**Action authorization and execution assurance for AI agents.** + +AgentPass is an action-control and evidence layer outside the agent loop. It +decides whether a specific agent action may execute and preserves durable, +independently verifiable evidence of what was authorized and executed. + +The canonical one-sentence promise is: + +> AgentPass controls consequential AI agent actions and produces independently +> verifiable evidence of what was authorized and executed. + +## Product Hierarchy + +### 1. Runtime Authorization And Control + +This is the core product. AgentPass evaluates the exact tool, arguments, +resource, principal, agent, job state, approval, budget, data-flow boundary, +and prior execution state immediately before dispatch. It can allow, deny, or +challenge the action and can prevent unsafe retries and duplicate effects. + +### 2. Portable Provider Trust And Interoperability + +This is the cross-boundary differentiator. Signed, action-bound authorization +evidence lets an MCP server, SaaS API, or other provider independently verify +the decision before applying its own business authorization. Public mappings, +fixtures, reference verifiers, and conformance suites make that behavior +testable across implementations. + +### 3. Execution And Outcome Assurance + +This completes the lifecycle. Provider execution receipts, immutable evidence, +verified observations, causal traces, and intent assessments establish what +happened after authorization and whether the intended outcome was achieved +within constraints. + +The layers compose as: + +```text +Identity and workload context + -> runtime authorization and control + -> portable provider verification + -> execution and outcome assurance +``` + +## Capability Story + +Lead with operational control: + +- stateful policy at the tool-execution boundary; +- exact-action approvals and step-up authorization; +- idempotency, replay protection, budgets, and circuit breakers; +- PII and sensitive-data movement controls; and +- explainable decisions and durable audit evidence. + +Then explain the differentiator: + +- authorization evidence bound to the exact action; +- independent verification across organizational or provider boundaries; +- linked execution closure and outcome evidence; and +- open interoperability fixtures and conformance tests. + +## Audience Entry Points + +| Audience | Lead with | +|---|---| +| Enterprise and security teams | Control consequential agent actions with policy, approvals, state, and audit | +| Agent and application developers | Add a small authorization boundary around existing tool calls | +| MCP gateway and platform builders | Enforce consistent action policy before forwarding `tools/call` | +| SaaS, API, and MCP providers | Independently verify action-specific authorization before mutation | +| Risk, compliance, and assurance teams | Link authorization, execution, observations, and assessment evidence | +| Standards and open-source communities | Reusable mappings, test vectors, profiles, and implementation feedback | + +## Standards And Open-Source Strategy + +Identity establishes the actors. Policy decides. AgentPass enforces and proves +the authority for a specific action, then links it to execution evidence. + +AgentPass reuses OIDC, OAuth, AuthZEN, SPIFFE, WIMSE, MCP authorization, JOSE, +HTTP Message Signatures, Shared Signals, and provenance work where applicable. +Its standards role is to contribute mappings, negative fixtures, reference +implementations, conformance tests, and narrowly scoped profiles before +proposing new vocabulary. + +Conformance is how AgentPass proves portability; it is not the product +category. Passing an AgentPass suite means agreement with experimental +AgentPass reference cases, not certification by an external standards body. + +## What AgentPass Is Not + +AgentPass is not: + +- an identity provider or universal agent registry; +- a new DID method or OAuth replacement; +- a replacement for MCP authorization, AuthZEN, SPIFFE, WIMSE, OPA, or Cedar; +- a substitute for provider business authorization; +- a prompt-safety system controlled by the model; or +- an observability product that merely records an action after it occurs. + +## Messaging Guardrails + +- Lead with concrete actions and failure modes, not abstract agent identity. +- Describe identity as an input to authorization, not the product category. +- Describe provider verification as the differentiator, not the entire product. +- Describe conformance and standards participation as the ecosystem strategy. +- Use “deterministic” only for enforceable policy and state transitions, not + model behavior. +- Preserve experimental labels and avoid unsupported certification claims. + +## Current Proof + +The repository already demonstrates the hierarchy through: + +- local guards, MCP adapters, gateways, approvals, and stateful controls; +- provider contracts, JWS/JWKS receipts, provider middleware, and conformance + cases; and +- execution receipts, evidence snapshots, verified observations, and intent + assurance. + +The next external proof milestone is two independent providers passing the same +public action-authorization suite without AgentPass-specific coordination at +runtime. diff --git a/docs/standards-alignment.md b/docs/standards-alignment.md index 19347aa..da1f22f 100644 --- a/docs/standards-alignment.md +++ b/docs/standards-alignment.md @@ -1,10 +1,11 @@ # Standards Alignment -AgentPass aligns with distributed identity and authorization standards as an -open reference implementation and conformance project for action-bound -authorization. It does not create a general agent identity or replace those -standards. The detailed project boundary is in -[Interoperability Positioning](interoperability-positioning.md). +AgentPass's product category is action authorization and execution assurance, +as defined in [Project Positioning](positioning.md). Within its standards work, +AgentPass acts as an open reference implementation and conformance project for +action-bound authorization. It does not create a general agent identity or +replace existing identity and authorization standards. The detailed standards +boundary is in [Interoperability Positioning](interoperability-positioning.md). For the current field-level mapping across AuthZEN, OAuth, WIMSE, SPIFFE, MCP, authorization-evidence proposals, and execution provenance, see the diff --git a/pyproject.toml b/pyproject.toml index 271d02a..13a7246 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "agentpass" version = "0.2.0" -description = "Authorization contracts, policy checks, and receipts for AI agent tool calls across MCP gateways, SaaS APIs, and enterprise systems." +description = "Action authorization, runtime controls, and independently verifiable execution evidence for AI agent tool calls." readme = "README.md" requires-python = ">=3.10" license = { text = "Apache-2.0" } diff --git a/tests/test_positioning_docs.py b/tests/test_positioning_docs.py new file mode 100644 index 0000000..7d6f51c --- /dev/null +++ b/tests/test_positioning_docs.py @@ -0,0 +1,101 @@ +from __future__ import annotations + +import re +from pathlib import Path + + +ROOT = Path(__file__).resolve().parent.parent +README = (ROOT / "README.md").read_text(encoding="utf-8") +POSITIONING = (ROOT / "docs" / "positioning.md").read_text(encoding="utf-8") +ROADMAP = (ROOT / "docs" / "action-gate-roadmap.md").read_text(encoding="utf-8") +INTEROPERABILITY = (ROOT / "docs" / "interoperability-positioning.md").read_text( + encoding="utf-8" +) +STANDARDS = (ROOT / "docs" / "standards-alignment.md").read_text(encoding="utf-8") +PYPROJECT = (ROOT / "pyproject.toml").read_text(encoding="utf-8") + +CATEGORY = "Action authorization and execution assurance for AI agents." +PROMISE = ( + "AgentPass controls consequential AI agent actions and produces independently\n" + "> verifiable evidence of what was authorized and executed." +) +LAYERS = [ + "Runtime authorization and control", + "Portable provider trust and interoperability", + "Execution and outcome assurance", +] + + +def test_readme_leads_with_product_category_and_canonical_positioning(): + assert README.startswith(f"# AgentPass\n\n**{CATEGORY}**") + assert PROMISE in README + assert "[Project Positioning](docs/positioning.md)" in README + assert ( + "conformance work demonstrates interoperability; it is not the product category" + in README + ) + assert (ROOT / "docs" / "positioning.md").is_file() + + +def test_canonical_positioning_contains_required_hierarchy_and_boundaries(): + assert f"**{CATEGORY}**" in POSITIONING + assert PROMISE in POSITIONING + for heading in [ + "## Product Hierarchy", + "## Capability Story", + "## Audience Entry Points", + "## Standards And Open-Source Strategy", + "## What AgentPass Is Not", + "## Messaging Guardrails", + ]: + assert heading in POSITIONING + for audience in [ + "Enterprise and security teams", + "Agent and application developers", + "MCP gateway and platform builders", + "SaaS, API, and MCP providers", + "Standards and open-source communities", + ]: + assert audience in POSITIONING + assert "Conformance is how AgentPass proves portability" in POSITIONING + assert "not certification by an external standards body" in POSITIONING + + +def test_readme_and_roadmap_share_the_three_product_layers(): + assert "[Project Positioning](positioning.md)" in ROADMAP + for layer in LAYERS: + assert layer in README + assert layer in ROADMAP + assert layer.title() in POSITIONING + assert "Framework wrappers and conformance suites are delivery mechanisms" in README + assert "They advance these layers rather than forming separate product" in ROADMAP + + +def test_interoperability_and_package_metadata_support_product_positioning(): + assert "open ecosystem strategy" in INTEROPERABILITY + assert "[Project Positioning](positioning.md)" in INTEROPERABILITY + assert ( + "AgentPass's product category is action authorization and execution assurance" + in STANDARDS + ) + assert "Within its standards work" in STANDARDS + assert ( + 'description = "Action authorization, runtime controls, and independently ' + 'verifiable execution evidence for AI agent tool calls."' + ) in PYPROJECT + + +def test_changed_positioning_documents_have_valid_local_links(): + documents = [ + ROOT / "README.md", + ROOT / "docs" / "positioning.md", + ROOT / "docs" / "interoperability-positioning.md", + ROOT / "docs" / "standards-alignment.md", + ] + for document in documents: + text = document.read_text(encoding="utf-8") + for link in re.findall(r"!?\[[^\]]*\]\(([^)]+)\)", text): + path = link.split("#", 1)[0] + if not path or "://" in path or path.startswith("mailto:"): + continue + assert (document.parent / path).exists(), f"broken link in {document}: {link}"