From c16ed0ce2b9b11ef368f580758d2d3e20af85876 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Fri, 10 Jul 2026 01:53:14 +0300 Subject: [PATCH 1/8] Add interactive RFC review --- review/agent-surface-rfc-review.html | 2326 ++++++++++++++++++++++++++ 1 file changed, 2326 insertions(+) create mode 100644 review/agent-surface-rfc-review.html diff --git a/review/agent-surface-rfc-review.html b/review/agent-surface-rfc-review.html new file mode 100644 index 0000000..a8866a7 --- /dev/null +++ b/review/agent-surface-rfc-review.html @@ -0,0 +1,2326 @@ + + + + + + + +Agent Surface Protocol — Interactive RFC Review + + + +
+
+
+
+

Agent Surface Protocol Specification

+

Request for Comments

+

Authors' Contact Information

+
    +
  • Egor Merkushev
    • +
  • Organization: Individual
    • +
  • Email: gorkaedeep@gmail.com
    • +
  • Published: 25 June 2026
    • +
+

Status of this Memo

+

This document is an Experimental Request for Comments. It represents a draft +proposal for an Agent Surface Protocol specification and is submitted to the +community for discussion, feedback, critique, and suggestions for improvement. +This document is a work in progress and is not yet a finalized standard. +Distribution of this memo is unlimited.

+

Submit comments as GitHub issues in the original repository hosting this RFC.

+ +

Copyright (c) 2026 0AL -- Zero-trust Agents Layer.

+

This document is released under the Creative Commons Attribution 4.0 +International License (CC BY 4.0). You are free to copy, distribute, and modify +this specification, even for commercial purposes, provided that attribution is +given to the original author(s).

+

To contribute to this document, please submit an issue or pull request to the +original GitHub repository:

+
https://github.com/0al-spec/agent-surface
+
+

This is not an IETF document and is not subject to BCP 78 or the IETF Trust. +However, it follows similar principles of openness and community participation.

+

Abstract

+

This proposal defines Agent Surface Protocol, a user-mediated delegation +model for connecting user-owned agents to application contexts, including web +applications and SaaS products.

+

Agent Surface Protocol can be understood as the missing protocol substrate for +safe Bring Your Own Agent (BYOA). BYOA describes the user expectation: a +person can bring a preferred local, enterprise, or hosted agent +into an application context. Agent Surface Protocol defines the security and +interoperability machinery that makes that expectation practical.

+

The central idea is not that an application "gets an agent". The user remains +the principal. The application publishes a typed Agent Surface describing +the resources, actions, events, scopes, risk labels, approval requirements, +schemas, idempotency rules, receipts, endpoints, and revocation semantics it +supports. The user chooses a local or remote agent they own. An application +runtime verifies the agent's Agent Passport, obtains a scoped Agent Grant, +enforces local policy, supervises the agent, and mediates all application +actions.

+

The goal is to replace brittle "computer use" automation patterns:

+
    +
  • screenshot interpretation
    • +
  • mouse and keyboard control
    • +
  • accessibility-tree scraping
    • +
  • private API scraping
    • +
  • raw user API tokens handed to agents
    • +
+

with a typed, scoped, auditable, revocable, app-verifiable delegation layer.

+

Normative and Informative Sections

+

Unless otherwise stated, the following sections are normative:

+
    +
  • Terminology
    • +
  • Design Principles
    • +
  • Agent Surface Manifest
    • +
  • Risk Taxonomy
    • +
  • Approval Semantics
    • +
  • Idempotency
    • +
  • Agent Grant
    • +
  • Sessions and Actions
    • +
  • Receipts
    • +
  • Revocation Semantics
    • +
  • Error Model
    • +
  • Versioning and Compatibility
    • +
  • Security Considerations
    • +
  • Privacy Considerations
    • +
  • Conformance
    • +
+

The following sections are informative:

+
    +
  • Abstract
    • +
  • Motivation
    • +
  • Relationship to Existing Protocols
    • +
  • Conceptual Architecture
    • +
  • Protocol Layers
    • +
  • Capability Matching
    • +
  • Application MVP Mapping
    • +
  • Example End-to-End Flow
    • +
  • Open Questions
    • +
  • References
    • +
  • Appendices
    • +
+

Motivation

+

Modern agents need to work inside applications. Today, they often do this in one +of two fragile ways:

+
    +
  1. They operate the user interface by observing screenshots, clicking controls, +and reading accessibility trees.
    2. +
  2. They receive a user's broad API token and call ordinary application APIs +directly, often without an agent-specific contract, local policy mediation, +idempotency, or portable receipts.
    3. +
+

Both approaches have structural problems.

+

Computer-use automation is brittle. It depends on pixels, layout, timing, +browser state, accessibility labels, and undocumented UI behavior. It is hard to +authorize precisely and hard to audit semantically. The user can see the result, +but the application rarely receives machine-verifiable evidence of which agent +acted, under which delegation, against which policy, and why a write was allowed.

+

Raw-token API automation is powerful but unsafe. A token is a transport +artifact, not a delegation model. If an agent receives a broad source-control, +issue-tracker, chat, docs, or CRM token, the application can be unable to +distinguish the user from the user's agent, the runtime can be unable to +constrain the agent's behavior after token release, and receipts become +difficult to produce without custom integration.

+

Agent Surface Protocol introduces a safer frame:

+
BYOA is the model.
+Agent Surface is the protocol.
+Agent Grant is the authority.
+Agent Passport is the evidence.
+
+App exposes affordances.
+User delegates an agent.
+Runtime mediates and enforces.
+App verifies authorization.
+Agent acts only through typed, scoped actions.
+
+

The application becomes agent-native, but not agent-owned. It does not +need to build, host, pay for, or control the user's agent. It only needs to +publish a civilized surface and enforce grants on its side.

+

Goals

+
    +
  • +

    Define a protocol layer for safe Bring Your Own Agent (BYOA) in application +contexts.

    +
    • +
  • +

    Treat the user as the principal and the agent as a delegated worker.

    +
    • +
  • +

    Make Grant, not token, the primary authorization object.

    +
    • +
  • +

    Let applications publish typed resources, actions, events, schemas, scopes, +risk labels, idempotency rules, approval hints, receipt requirements, and +wire-level endpoints.

    +
    • +
  • +

    Let runtimes verify Agent Passports before an agent can receive delegated work.

    +
    • +
  • +

    Require both runtime-side and app-side enforcement.

    +
    • +
  • +

    Avoid direct application credentials in agent processes where practical.

    +
    • +
  • +

    Make proposal-first workflows the default safety posture:

    +
    read -> propose -> approve -> write -> receipt
+
    +
    • +
  • +

    Fit alongside existing agent standards instead of replacing them:

    +
      +
    • MCP can remain a tool/resource transport.
      • +
    • ACP can remain an agent/client transport.
      • +
    • OAuth can remain a consent and authorization substrate.
      • +
    • Agent Passport can remain identity and capability evidence.
      • +
    +
    • +
+

Non-Goals

+
    +
  • Do not define another general-purpose agent framework.
    • +
  • Do not replace MCP, ACP, OAuth, DID, Verifiable Credentials, JSON Schema, or +existing application APIs.
    • +
  • Do not require applications to trust local runtimes blindly.
    • +
  • Do not require agents to receive raw user credentials.
    • +
  • Do not require browser-to-localhost communication.
    • +
  • Do not require every app action to be autonomous; proposal mode is valid and +preferred for early adoption.
    • +
  • Do not standardize every possible human approval UI.
    • +
  • Do not specify a single cryptographic trust-store model in this draft.
    • +
  • Do not require signed grants or signed receipts in the MVP profile.
    • +
+

Conventions

+

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this +document are to be interpreted in the RFC 2119 and RFC 8174 sense when, and only +when, they appear in all capitals.

+

This is not an IETF document. The keywords are used to make interoperability and +security expectations explicit for future implementers.

+

Terminology

+

User

+

The human principal who owns or controls an account in an application and owns, +selects, or authorizes an agent.

+

Application

+

The product or software system that exposes a bounded environment in which +agents can operate. An application can be a website, SaaS product, desktop app +backend, local bridge, control plane, browser extension, reference +implementation, or service that publishes an Agent Surface and enforces +app-side authorization.

+

This draft uses Application as the neutral term for concrete +implementations. Product-specific names belong in implementation documents, not +in the protocol role model.

+

Agent Surface

+

The machine-readable map of application affordances available for agent +delegation. A surface includes resources, actions, events, schemas, scopes, risk +labels, approval hints, idempotency rules, audit semantics, versioning, endpoints, +and revocation semantics.

+

The surface is not merely an API endpoint list. It is an application contract for +safe delegated agent behavior.

+

Agent Surface Manifest

+

A discoverable document, typically published at a well-known URL such as:

+
/.well-known/agent-surface.json
+
+

The manifest describes the Agent Surface in a machine-readable format.

+

User-Owned Agent

+

An agent selected by the user. It can run locally, in a company-controlled +environment, or in a remote service. The important property is that the +application does not own or silently choose it.

+

Runtime

+

The local or user-controlled system that hosts, launches, supervises, or mediates +the user's agent. A runtime can be embedded in an application, delivered as a +companion bridge or daemon, provided by an operating system service, implemented +by a browser extension, or hosted in a user-controlled environment.

+

When the runtime is part of a concrete application implementation, this draft +refers to it as an application runtime.

+

This proposal separates two runtime responsibilities:

+
    +
  • Agent Host: starts or connects to agents, adapters, and tools.
    • +
  • Policy Enforcement Point: stores grants, applies local policy, obtains +approvals, mediates actions, writes audit logs, and blocks disallowed behavior.
    • +
+

One process can implement both roles, but the distinction matters for security +analysis.

+

Agent Passport

+

Agent Passport is identity and +capability evidence for an agent. It can describe the agent, its declared +capabilities, resource requirements, security policies, integrity hashes, +lifecycle, issuer, and signature.

+

An Agent Passport does not by itself grant authority inside an application. +It answers "what is this agent and what has been attested about it?" A grant +answers "what has this user allowed this runtime-agent-passport tuple to do in +this application context?"

+

Passport is evidence, not authority.

+

Agent Grant

+

A user-approved, app-scoped, policy-bound delegation object.

+

The grant is the semantic authorization. Tokens, cookies, JWTs, capability URLs, +sender-constrained credentials, or signed objects are transport representations. +A grant SHOULD be temporary, constrained, auditable, revocable, and bound to the +user, application, runtime, agent, and passport evidence.

+

Grant Credential

+

A concrete credential or proof used to represent or prove an Agent Grant on the +wire. Examples include opaque bearer tokens, sender-constrained tokens, DPoP +proofs, mTLS-bound tokens, JWTs, macaroon-like capabilities, signed delegation +objects, or app-side server sessions.

+

A grant_id is an identifier. It is not, by itself, authority.

+

Capability Lease

+

An informal term for a time-limited, attenuated grant. A capability lease grants +only specific capabilities, under caveats such as duration, resource bounds, +approval requirements, max actions, or max spend.

+

Action

+

A typed operation exposed by an Agent Surface. Examples:

+
    +
  • comment.propose
    • +
  • comment.create
    • +
  • pull_request.review.submit
    • +
  • task.assign
    • +
  • invoice.refund.request
    • +
+

Resource

+

A typed object or collection exposed by an Agent Surface. Examples:

+
    +
  • pull_request
    • +
  • issue
    • +
  • task
    • +
  • document
    • +
  • invoice
    • +
+

Event

+

A typed notification exposed by an Agent Surface or runtime. Examples:

+
    +
  • review.requested
    • +
  • ci.failed
    • +
  • task.created
    • +
  • grant.revoked
    • +
+

Receipt

+

Portable evidence that an action occurred, including the grant, session, agent, +passport hash, input hash, output hash, approval, timestamp, and result.

+

Receipts can be stored locally, in the application, in enterprise audit systems, +or in a provenance graph.

+

This proposal distinguishes:

+
    +
  • Runtime Receipt: evidence observed and produced by the runtime, such as +agent intent, policy evaluation, and local user approval.
    • +
  • App Receipt: evidence produced by the application that a mutation was +actually performed or denied under a grant.
    • +
+

Design Principles

+

User Is the Principal

+

The user chooses whether to delegate work to an agent. The app MAY expose a +surface and request consent, but it MUST NOT silently select an agent or claim +that a user's agent acts on behalf of the app.

+

App Exposes, Runtime Mediates, Agent Executes

+

The application exposes typed affordances. The runtime mediates access to those +affordances. The agent executes delegated work through the runtime.

+
User
+  -> authorizes grant
+Runtime / Policy Enforcement Point
+  -> verifies Agent Passport
+  -> supervises User-Owned Agent
+Agent
+  -> requests typed actions
+Runtime
+  -> enforces local policy and grant caveats
+Application
+  -> enforces app-side grant scopes
+
+

Grant Is More Important Than Token

+

A token is a bearer mechanism, proof key, or API credential. A grant is the +semantic delegation:

+
This user allowed this runtime-agent-passport tuple to perform these typed
+actions in this app context under these constraints until this expiration.
+
+

Implementations MAY represent a grant as an opaque token, OAuth access token, +sender-constrained token, signed object, macaroon-like capability, or server-side +grant identifier. The protocol model SHOULD still describe it as a grant.

+

Grant Identifier Is Not Authority

+

Applications MUST NOT authorize an action based only on a client-supplied +grant_id.

+

A request that includes grant_id MUST also be authorized by an app-verifiable +grant credential, server-side grant state, signed delegation object, +introspection result, sender-constrained proof, or equivalent authorization +mechanism.

+

App-Side Enforcement Is Mandatory

+

Runtime policy is necessary but not sufficient.

+

The runtime protects the user. The app protects its resources.

+

An application MUST verify grant authority for every action. It MUST NOT accept a +runtime's self-assertion that a grant exists without an app-verifiable token, +signed delegation object, introspection result, or equivalent authorization +mechanism.

+

Agent Does Not Receive Raw Authority

+

Where practical, the agent SHOULD NOT receive the grant secret, OAuth access +token, cookie, session key, or broad application credential. The agent SHOULD +request typed actions from the runtime:

+
Agent -> Runtime -> App Agent Surface
+
+

The runtime can then enforce local policy, approvals, idempotency, auditing, and +redaction before sending anything to the app.

+

Proposal Mode Is the Default

+

The first safe interaction mode SHOULD be:

+
read -> draft/propose -> human or app approval -> write -> receipt
+
+

Direct writes without approval can exist for mature grants and low-risk actions, +but the protocol SHOULD make proposal flows first-class.

+

Every Write Is Idempotent

+

Any action with side effects MUST support idempotency. Retries, network +reconnects, agent loops, and duplicate messages MUST NOT create ten comments, ten +branches, ten refund requests, or ten approvals.

+

Receipts Are First-Class

+

Audit logs are useful, but action receipts are portable. A receipt SHOULD be +created for every successful side-effecting action and for important denied or +failed actions.

+

Relationship to Existing Protocols

+

Model Context Protocol

+

The Model Context Protocol specification describes an open protocol for +connecting LLM applications to external data sources and tools:

+

https://modelcontextprotocol.io/specification/2025-06-18

+

MCP is primarily a context and tool integration protocol for agents and LLM +applications. It helps an agent reach external data sources and tools, including +data and operations that live inside applications, so the agent can enrich its +working context and call available tools.

+

That is different from admitting a user-owned agent into an application authority +model. MCP servers, direct CLI integrations, and direct API integrations can be +useful substrates below an agent or runtime, but they do not by themselves define +an app-native delegation contract, user-approved Agent Grants, app-side grant +enforcement, risk labels, approval semantics, revocation semantics, or portable +receipts.

+

More importantly, MCP makes agents more capable, but it does not by itself make +ordinary applications agentic. In an MCP-only integration, the application often +remains a data source or tool provider reached from the outside:

+
MCP-only:
+User <-> Application <- Agent <-> User
+
+

Agent Surface Protocol is the application augmentation layer. It gives an +ordinary application a typed way to accept a user-owned agent as a delegated +participant in application workflows:

+
ASP:
+User <-> Application <-> Agent <-> User
+
+

At the product level, this collapses into a simpler user experience:

+
User <-> AI-App
+
+

In this framing, the agent is not merely extracting application data to enrich +its own context. The application itself becomes AI-augmented: it exposes typed +affordances, receives user-authorized agent participation, and can render, +approve, constrain, revoke, and receipt agent work as part of the application +experience.

+

Agent Client Protocol

+

Agent Client Protocol focuses on communication between clients such as editors +and coding agents, including local and remote agent scenarios:

+

https://agentclientprotocol.com/protocol/v1/overview

+

ACP can be an Agent Adapter Protocol below an application runtime. Agent Surface +Protocol does not replace ACP; it defines how a user grants a user-owned agent +authority inside an application context.

+

Where ACP places environment management, user interaction, and resource access +under the Client role, ASP makes those responsibilities explicit as +Application-owned surfaces, grants, approvals, and receipts.

+

The practical composition is not "ASP or ACP". ACP can sit inside an +application, wrapped by ASP as the application-facing augmentation layer. In +Hypercode structural notation, with .hcs values and contracts omitted:

+
AIApplication
+  UserInterface
+  AgentSurfaceProtocolLayer
+    ApplicationResources
+    ApplicationActions
+    AgentGrantRegistry
+    ApprovalPolicy
+    ActionReceiptLog
+    ACPAgentAdapter
+      ApplicationRuntimeClient
+      UserOwnedAgent
+      AgentSession
+
+

In that shape, ACP standardizes the operational conversation between the +application runtime and the agent. ASP defines the application shell around that +conversation: what the application exposes, what the user delegates, what the +agent can do inside the product, and how the product presents, approves, +constrains, revokes, and receipts agent participation.

+
ACP:
+ApplicationRuntime <-> Agent
+
+ASP around ACP:
+User <-> Application
+          |
+          +-- ASP layer
+              |
+              +-- ACP adapter <-> Agent
+
+Product view:
+User <-> AI-App
+
+

OAuth

+

OAuth 2.0 remains a practical substrate for consent, authorization codes, scopes, +refresh, revocation, token introspection, token exchange, and resource +indicators.

+

Relevant standards:

+ +

Agent Surface Protocol uses the term grant for the semantic object, +even when an OAuth access token is the transport representation.

+

If OAuth is used, agent_delegation MAY be represented as an OAuth extension +grant type. agent_delegation is not a standard OAuth grant type in this draft.

+

Implementations MAY also use existing OAuth flows, including:

+
    +
  • Authorization Code with PKCE and additional agent delegation parameters.
    • +
  • OAuth Token Exchange to exchange a user-authorized credential for an +agent-scoped grant credential.
    • +
  • Resource Indicators to constrain the resource server or app surface.
    • +
+

Agent Passport

+

Agent Passport provides agent +identity, capability, policy, lifecycle, signature, and integrity evidence.

+

Agent Surface Protocol consumes Agent Passport evidence during grant issuance and +runtime mediation:

+
    +
  • Is this agent known?
    • +
  • Who issued or signed its passport?
    • +
  • What capabilities does it declare?
    • +
  • What runtime or resource constraints does it require?
    • +
  • Has the passport expired or been revoked?
    • +
  • Does the passport hash match the executable agent?
    • +
+

But the passport itself does not authorize application actions.

+

DID and Verifiable Credentials

+

Decentralized Identifiers and Verifiable Credentials can be useful for future +signed grants, issuer trust, and portable delegation proofs:

+ +

This draft does not require DID or VC for the MVP.

+

Conceptual Architecture

+
Browser / App UI
+        |
+        | HTTPS / SSE / WebSocket
+        v
+Application Control Plane
+  - publishes Agent Surface Manifest
+  - issues or validates Agent Grants
+  - enforces app-side scopes
+  - emits app events
+        ^
+        | outbound WSS / HTTPS from runtime
+        v
+Application Runtime
+  - pairs with app/account
+  - verifies Agent Passport
+  - stores grants
+  - applies local policy
+  - obtains local approvals
+  - supervises agent adapters
+  - writes audit log and receipts
+        |
+        | adapter boundary
+        v
+User-Owned Agent
+  - local CLI agent
+  - hosted coding agent
+  - ACP agent
+  - MCP-backed workflow
+  - custom command
+
+

The browser can interact with the application control plane. It does not need to +connect directly to the local runtime.

+

Protocol Layers

+

Agent Surface Protocol is specified as four separable layers.

+

1. Agent Surface Manifest

+

The application-published affordance contract:

+
    +
  • app identity
    • +
  • surface version
    • +
  • resources
    • +
  • actions
    • +
  • events
    • +
  • scopes
    • +
  • JSON Schemas
    • +
  • risk labels
    • +
  • approval hints
    • +
  • idempotency requirements
    • +
  • receipt requirements
    • +
  • auth endpoints
    • +
  • action endpoints
    • +
  • event endpoints
    • +
  • receipt endpoints
    • +
  • revocation endpoints
    • +
+

2. Agent Grant Protocol

+

The user-mediated authorization lifecycle:

+
    +
  • grant request
    • +
  • consent presentation
    • +
  • runtime binding
    • +
  • agent binding
    • +
  • passport binding
    • +
  • scope constraints
    • +
  • expiration
    • +
  • refresh
    • +
  • revocation
    • +
  • introspection
    • +
  • receipt linkage
    • +
+

3. Runtime Bridge Protocol

+

The runtime-to-control-plane channel. A conforming application MAY expose this +kind of channel using typed session and approval messages such as:

+
    +
  • runtime.hello
    • +
  • runtime.accepted
    • +
  • session.start
    • +
  • session.event
    • +
  • session.cancel
    • +
  • approval.required
    • +
  • approval.resolved
    • +
+

This layer is transport and session orchestration. It is not intended to absorb +all Agent Surface semantics.

+

4. Agent Adapter Protocol

+

The runtime-to-agent integration layer:

+
    +
  • custom-command
    • +
  • codex-cli
    • +
  • claude-code
    • +
  • acp-stdio
    • +
  • mcp-client
    • +
  • mcp-server
    • +
+

The adapter layer turns a concrete agent into a runtime-mediated worker.

+

Agent Surface Manifest

+

Discovery

+

Applications SHOULD publish a manifest at:

+
https://example.com/.well-known/agent-surface.json
+
+

For multi-tenant SaaS systems, the public well-known manifest SHOULD describe +tenant-independent capabilities. Tenant-specific surfaces MAY be discovered +through authenticated application metadata or through tenant-specific origins, +such as:

+
https://tenant.example.com/.well-known/agent-surface.json
+
+

If the manifest contains sensitive tenant-specific affordances, it MUST require +ordinary authenticated app access.

+

The manifest SHOULD be served with:

+
Content-Type: application/json
+Cache-Control: max-age=300
+
+

Required Top-Level Fields

+
{
+  "protocol": "agent-surface/0.1",
+  "app_id": "com.example.project-tool",
+  "issuer": "https://example.com",
+  "surface_version": "2026-06-25",
+  "surface_url": "https://example.com/.well-known/agent-surface.json",
+  "auth": {},
+  "agent_api": {},
+  "scopes": [],
+  "resources": [],
+  "actions": [],
+  "events": [],
+  "audit": {},
+  "revocation": {}
+}
+
+

Endpoints

+

The manifest MUST declare enough endpoint information for a runtime to obtain or +validate a grant and invoke typed actions.

+

This draft separates OAuth-style authorization endpoints from application action +endpoints.

+

Example:

+
{
+  "auth": {
+    "type": "oauth2",
+    "authorization_url": "https://example.com/oauth/authorize",
+    "token_url": "https://example.com/oauth/token",
+    "introspection_url": "https://example.com/oauth/introspect",
+    "revocation_url": "https://example.com/oauth/revoke"
+  },
+  "agent_api": {
+    "grant_request_url": "https://example.com/agent-grants/request",
+    "grant_introspection_url": "https://example.com/agent-grants/introspect",
+    "grant_revocation_url": "https://example.com/agent-grants/revoke",
+    "action_url": "https://example.com/agent-actions",
+    "event_subscription_url": "https://example.com/agent-events",
+    "receipt_url": "https://example.com/agent-receipts"
+  }
+}
+
+

Implementations MAY collapse these endpoints when the application already has +equivalent OAuth or API infrastructure, but the manifest MUST make the wire-level +surface discoverable.

+

Example Manifest

+
{
+  "protocol": "agent-surface/0.1",
+  "app_id": "com.example.project-tool",
+  "issuer": "https://example.com",
+  "surface_version": "2026-06-25",
+  "surface_url": "https://example.com/.well-known/agent-surface.json",
+  "compatibility": {
+    "min_runtime": "application-runtime/0.1",
+    "schema_dialect": "https://json-schema.org/draft/2020-12/schema"
+  },
+  "auth": {
+    "type": "oauth2",
+    "authorization_url": "https://example.com/oauth/authorize",
+    "token_url": "https://example.com/oauth/token",
+    "introspection_url": "https://example.com/oauth/introspect",
+    "revocation_url": "https://example.com/oauth/revoke",
+    "grant_types": ["agent_delegation"],
+    "token_binding": ["runtime", "agent_passport_hash"],
+    "pkce_required": true
+  },
+  "agent_api": {
+    "grant_request_url": "https://example.com/agent-grants/request",
+    "grant_introspection_url": "https://example.com/agent-grants/introspect",
+    "grant_revocation_url": "https://example.com/agent-grants/revoke",
+    "action_url": "https://example.com/agent-actions",
+    "event_subscription_url": "https://example.com/agent-events",
+    "receipt_url": "https://example.com/agent-receipts"
+  },
+  "scopes": [
+    {
+      "id": "tasks.read",
+      "description": "Read tasks visible to the user."
+    },
+    {
+      "id": "comments.propose",
+      "description": "Prepare comments without committing them."
+    },
+    {
+      "id": "comments.write",
+      "description": "Create comments in the application."
+    }
+  ],
+  "resources": [
+    {
+      "id": "task",
+      "read_scope": "tasks.read",
+      "schema": "https://example.com/schemas/task.schema.json"
+    }
+  ],
+  "actions": [
+    {
+      "id": "comment.propose",
+      "scope": "comments.propose",
+      "risk": "propose",
+      "side_effect": false,
+      "approval": "none",
+      "execution": {
+        "mode": "direct"
+      },
+      "input_schema": "https://example.com/schemas/comment-propose.input.schema.json",
+      "output_schema": "https://example.com/schemas/comment-propose.output.schema.json"
+    },
+    {
+      "id": "comment.create",
+      "scope": "comments.write",
+      "risk": "write",
+      "side_effect": true,
+      "approval": "user_or_app",
+      "idempotency": "required",
+      "execution": {
+        "mode": "write",
+        "proposal_action": "comment.propose"
+      },
+      "input_schema": "https://example.com/schemas/comment-create.input.schema.json",
+      "output_schema": "https://example.com/schemas/comment-create.output.schema.json",
+      "receipt": "required"
+    }
+  ],
+  "events": [
+    {
+      "id": "task.created",
+      "scope": "tasks.read",
+      "schema": "https://example.com/schemas/task-created.event.schema.json"
+    },
+    {
+      "id": "review.requested",
+      "scope": "tasks.read",
+      "schema": "https://example.com/schemas/review-requested.event.schema.json"
+    }
+  ],
+  "audit": {
+    "receipt_schema": "https://example.com/schemas/action-receipt.schema.json",
+    "required_fields": [
+      "grant_id",
+      "session_id",
+      "action_id",
+      "actor_agent",
+      "user",
+      "timestamp",
+      "result"
+    ]
+  },
+  "revocation": {
+    "grant_revocation_url": "https://example.com/agent-grants/revoke",
+    "event": "grant.revoked"
+  }
+}
+
+

Resources

+

Resources describe data the agent MAY read, reference, or attach to an action.

+

Each resource SHOULD include:

+
    +
  • id
    • +
  • read_scope
    • +
  • schema
    • +
  • optional query_actions
    • +
  • optional redaction_policy
    • +
  • optional retention_policy
    • +
+

Example:

+
{
+  "id": "pull_request",
+  "read_scope": "pull_request.read",
+  "schema": "https://github.example/schemas/pull-request.schema.json",
+  "query_actions": ["pull_request.get", "pull_request.list_files"],
+  "redaction_policy": "repository-visible-fields-only"
+}
+
+

Actions

+

Actions are typed operations the app allows agents to request through a runtime.

+

Each action SHOULD include:

+
    +
  • id
    • +
  • scope
    • +
  • risk
    • +
  • approval
    • +
  • input_schema
    • +
  • output_schema
    • +
  • side_effect
    • +
  • execution
    • +
  • idempotency for side-effecting actions
    • +
  • receipt for side-effecting actions
    • +
+

Example:

+
{
+  "id": "pull_request.review.submit",
+  "scope": "pull_request.review.write",
+  "risk": "write",
+  "side_effect": true,
+  "approval": "user_or_app",
+  "idempotency": "required",
+  "execution": {
+    "mode": "write",
+    "proposal_action": "pull_request.review.propose"
+  },
+  "input_schema": "https://example.com/schemas/pr-review-submit.input.schema.json",
+  "output_schema": "https://example.com/schemas/pr-review-submit.output.schema.json",
+  "receipt": "required"
+}
+
+

Proposal-Only Support

+

Applications that are not ready to allow direct agent writes SHOULD expose +proposal-only actions.

+

A proposal-only action is a typed action whose output is a draft, suggestion, +patch, review body, or other non-committed artifact.

+

Example:

+
{
+  "id": "pull_request.review.propose",
+  "scope": "pull_request.review.propose",
+  "risk": "propose",
+  "side_effect": false,
+  "approval": "none",
+  "execution": {
+    "mode": "proposal_only"
+  },
+  "input_schema": "https://example.com/schemas/pr-review-propose.input.schema.json",
+  "output_schema": "https://example.com/schemas/pr-review-propose.output.schema.json"
+}
+
+

If a write action depends on a proposal, it SHOULD reference the proposal action:

+
{
+  "id": "pull_request.review.submit",
+  "execution": {
+    "mode": "write",
+    "proposal_action": "pull_request.review.propose"
+  }
+}
+
+

This allows early adopters to become agent-native without allowing direct writes.

+

Events

+

Events let applications notify runtimes and agents about app context changes.

+

Events SHOULD be scoped. A grant that permits pull_request.read MAY receive +pull_request.updated, but SHOULD NOT receive unrelated financial, HR, or admin +events.

+

Example:

+
{
+  "id": "ci.failed",
+  "scope": "pull_request.read",
+  "schema": "https://example.com/schemas/ci-failed.event.schema.json"
+}
+
+

Risk Taxonomy

+

Every action SHOULD have a standard risk label. Runtimes can map risk labels to +local policy defaults.

+

| Risk | Meaning | Suggested Default | +| --- | --- | --- | +| read | Reads data visible under the grant. | Allow if scope permits. | +| propose | Produces a draft, suggestion, or patch without committing it. | Allow and audit. | +| write | Mutates app state. | Ask or require app approval. | +| public_side_effect | Publishes, sends, or exposes user-visible or public content. | Ask; often require app-side confirmation. | +| external_side_effect | Sends data or causes effects outside the app boundary. | Ask; often deny by default. | +| financial_side_effect | Charges, refunds, purchases, invoices, payroll. | Always require explicit approval. | +| destructive | Deletes, closes, revokes, disables, or irreversibly changes state. | Deny by default or require step-up approval. | +| privileged | Changes permissions, secrets, tokens, admin settings, or access policy. | Deny by default. |

+

Applications MAY define extension risk labels, but they SHOULD map them to the +standard labels for runtime interoperability.

+

Approval Semantics

+

Actions SHOULD declare an approval mode:

+

| Approval | Meaning | +| --- | --- | +| none | Runtime MAY execute if grant and policy allow. | +| runtime | Runtime MUST obtain local user approval before sending the action. | +| app | App MUST obtain or verify app-side approval before committing. | +| user_or_app | Either a runtime approval or app-side approval MAY satisfy the requirement, depending on grant caveats. | +| runtime_and_app | Both runtime-side and app-side approval are required. |

+

Approval records SHOULD be linked into receipts.

+

Idempotency

+

Every side-effecting action MUST support idempotency.

+

Action requests SHOULD include:

+
{
+  "idempotency_key": "idem_01HX...",
+  "action_id": "comment.create"
+}
+
+

The application MUST ensure repeated requests with the same idempotency key and +same normalized input do not repeat the side effect.

+

If the same key is reused with different normalized input, the application SHOULD +return an idempotency conflict error.

+

Applications SHOULD define the input normalization procedure per action, or use +the declared input schema with a canonical JSON profile. A future draft is +expected to define canonicalization requirements for signed receipts and signed +grants.

+

Agent Grant

+

Grant Object

+

An Agent Grant binds a user, runtime, agent, passport evidence, application, +surface, scopes, and caveats.

+
{
+  "grant_id": "grant_123",
+  "subject": {
+    "user": "user_abc"
+  },
+  "delegate": {
+    "runtime": "application_runtime_456",
+    "agent": "local_agent_789",
+    "passport_ref": "agent-passport://local-agent",
+    "passport_hash": "sha256:..."
+  },
+  "resource_server": {
+    "app_id": "code.example.com",
+    "issuer": "https://code.example.com",
+    "surface_version": "code-review-agent-surface/0.1"
+  },
+  "scopes": [
+    "pull_request.read",
+    "pull_request.comment"
+  ],
+  "constraints": {
+    "repositories": ["example-org/example-repo"],
+    "pull_requests": [13],
+    "expires_at": "2026-06-25T20:00:00Z",
+    "write_approval": "required",
+    "max_actions": 20,
+    "max_cost_usd": 5
+  },
+  "audit": {
+    "local_receipt": "required",
+    "app_receipt": "required"
+  }
+}
+
+

Grant Lifecycle

+
discover surface
+  -> verify manifest
+  -> choose agent
+  -> verify Agent Passport
+  -> request grant
+  -> user consent
+  -> issue grant
+  -> store grant in runtime
+  -> start session
+  -> mediate actions
+  -> issue receipts
+  -> expire / revoke / renew
+
+

Grant Issuance Models

+

Model A: App-Issued Grant

+

The application issues a grant after user consent.

+
Runtime redirects user to app OAuth / consent
+App issues agent grant
+Runtime stores grant
+Runtime calls app with grant credential
+App verifies every call
+
+

This is the RECOMMENDED MVP model because it fits existing OAuth/resource-server +deployments.

+

Pros:

+
    +
  • Easy for applications to enforce.
    • +
  • Works with existing consent and scope infrastructure.
    • +
  • Does not require a new global trust authority.
    • +
+

Cons:

+
    +
  • The app learns runtime and agent metadata.
    • +
  • Each app needs to implement agent grant issuance.
    • +
+

Model B: Runtime-Held Grant Plus App Token

+

The app issues a scoped token to the runtime. The runtime locally binds that +token to an agent, passport, and policy.

+

Pros:

+
    +
  • Simpler for early app integrations.
    • +
  • Can work with existing OAuth tokens.
    • +
+

Cons:

+
    +
  • The app can fail to know which agent actually acted.
    • +
  • Weaker app-side audit unless receipts include runtime-attested metadata.
    • +
+

Model C: Signed Delegation Object

+

The grant is a signed object with caveats. It MAY be signed by the app, user, +runtime, enterprise authority, or some combination.

+

Pros:

+
    +
  • Portable and cryptographically strong.
    • +
  • Can support offline verification and third-party audit.
    • +
+

Cons:

+
    +
  • Requires canonicalization, trust stores, signing profiles, revocation +semantics, and stronger interop work.
    • +
  • Too large for the first MVP.
    • +
+

Grant Credentials and Proof

+

An Agent Grant MAY be represented or proven by one of several mechanisms:

+
    +
  • bearer grant token
    • +
  • sender-constrained token
    • +
  • DPoP-bound token
    • +
  • mTLS-bound token
    • +
  • app-side server session binding
    • +
  • token introspection result
    • +
  • signed delegation object
    • +
  • macaroon-like caveated capability
    • +
+

A future draft is expected to define required proof profiles. The MVP profile +MAY use app-issued bearer grant credentials, but production deployments SHOULD +prefer sender-constrained credentials where practical.

+

Grant Verification

+

Applications SHOULD verify every action against grant state:

+
    +
  • grant exists and is active
    • +
  • grant credential or proof is valid
    • +
  • grant is bound to the user
    • +
  • grant is bound to the runtime when binding is required
    • +
  • grant is bound to the agent/passport hash when binding is required
    • +
  • scope permits the action
    • +
  • resource constraints permit the target object
    • +
  • expiration has not passed
    • +
  • action count and cost bounds have not been exceeded
    • +
  • approval caveats are satisfied
    • +
  • idempotency key is valid
    • +
+

Runtimes SHOULD verify:

+
    +
  • grant is active
    • +
  • local user has not revoked the app, runtime, or agent
    • +
  • Agent Passport is valid
    • +
  • requested action is compatible with the Agent Passport capability set
    • +
  • local policy allows the action
    • +
  • local approval is present when required
    • +
  • action input matches the declared schema
    • +
  • secrets and credentials are not exposed to the agent
    • +
+

Capability Matching

+

Capability matching is an advisory process used by the runtime to help the user +choose a compatible agent. It does not invert authority.

+

Incorrect framing:

+
The app needs an agent with capability X, so the runtime picks one.
+
+

Correct framing:

+
The app exposes actions X/Y/Z.
+The user wants to delegate work in that app.
+The runtime compares app requirements with passports of user-owned agents.
+The user authorizes a specific runtime-agent-passport tuple through a grant.
+
+

Matching inputs:

+
    +
  • action capability_hint
    • +
  • action schemas
    • +
  • required scopes
    • +
  • risk labels
    • +
  • Agent Passport capabilities
    • +
  • Agent Passport security policy
    • +
  • local runtime adapter availability
    • +
  • user preferences
    • +
  • enterprise policy
    • +
+

Matching outputs:

+
    +
  • compatible agents
    • +
  • missing capabilities
    • +
  • required scopes
    • +
  • required approvals
    • +
  • risk summary
    • +
  • expected sandbox constraints
    • +
+

The matching result is shown to the user before grant issuance.

+

Sessions and Actions

+

Session Start

+

Once a grant exists, an application or runtime MAY start a session.

+
{
+  "type": "session.start",
+  "payload": {
+    "session_id": "sess_456",
+    "grant_id": "grant_123",
+    "agent_id": "local_agent_789",
+    "surface": {
+      "app_id": "code.example.com",
+      "surface_version": "code-review-agent-surface/0.1"
+    },
+    "task": {
+      "kind": "pull_request.review",
+      "goal": "Review PR #13 and propose a concise review comment.",
+      "inputs": {
+        "repository": "example-org/example-repo",
+        "pull_request": 13
+      }
+    }
+  }
+}
+
+

Action Request

+

The agent requests an action through the runtime. The runtime sends the action to +the app only if grant and policy allow it.

+

The action request MUST be authorized by the HTTP authorization layer or an +equivalent proof. The grant_id inside the body is a correlation identifier, not +a credential.

+

Example:

+
POST /agent-actions HTTP/1.1
+Host: example.com
+Authorization: Bearer <grant-credential>
+Idempotency-Key: idem_01HX7DS8AC6G9
+Content-Type: application/json
+
+
{
+  "type": "action.request",
+  "payload": {
+    "session_id": "sess_456",
+    "grant_id": "grant_123",
+    "action_id": "comment.create",
+    "idempotency_key": "idem_01HX7DS8AC6G9",
+    "input": {
+      "repository": "example-org/example-repo",
+      "pull_request": 13,
+      "body": "The proposed review comment text."
+    }
+  }
+}
+
+

If the runtime uses a signed proof instead of a bearer grant credential, the +request SHOULD carry proof material in a standard authorization header or an +explicit proof field.

+

Example proof shape:

+
{
+  "proof": {
+    "type": "dpop+jwt",
+    "jti": "proof_123",
+    "iat": 1782400000,
+    "signature": "..."
+  }
+}
+
+

Action Response

+
{
+  "type": "action.result",
+  "payload": {
+    "session_id": "sess_456",
+    "grant_id": "grant_123",
+    "action_id": "comment.create",
+    "idempotency_key": "idem_01HX7DS8AC6G9",
+    "result": "success",
+    "resource": {
+      "type": "comment",
+      "id": "comment_789",
+      "url": "https://code.example.com/example-org/example-repo/pull/13#discussion_r..."
+    },
+    "receipt_id": "receipt_abc"
+  }
+}
+
+

Proposal Flow

+

Proposal mode separates drafting from committing.

+
Agent -> comment.propose
+Runtime -> local policy check
+App -> stores draft/proposal
+User/App -> approves
+App -> comment.create
+Runtime/App -> receipt
+
+

This is the RECOMMENDED default for early integrations.

+

Receipts

+

Receipt Requirements

+

Receipts SHOULD include:

+
    +
  • receipt id
    • +
  • receipt type
    • +
  • grant id
    • +
  • session id
    • +
  • action id
    • +
  • app id
    • +
  • user id or stable pseudonymous user reference
    • +
  • runtime id
    • +
  • agent id
    • +
  • Agent Passport hash
    • +
  • surface version
    • +
  • input hash
    • +
  • output hash
    • +
  • approval reference
    • +
  • idempotency key
    • +
  • timestamp
    • +
  • result
    • +
  • error classification when failed
    • +
+

Runtime Receipt

+

A runtime receipt records what the runtime observed and enforced, such as agent +intent, local policy decisions, local approvals, denials, and runtime-side +redactions.

+
{
+  "receipt_id": "receipt_runtime_abc",
+  "receipt_type": "runtime",
+  "grant_id": "grant_123",
+  "session_id": "sess_456",
+  "action_id": "comment.create",
+  "actor_agent": {
+    "agent_id": "local_agent_789",
+    "passport_hash": "sha256:..."
+  },
+  "runtime": {
+    "runtime_id": "application_runtime_456"
+  },
+  "subject": {
+    "user": "user_abc"
+  },
+  "idempotency_key": "idem_01HX7DS8AC6G9",
+  "input_hash": "sha256:...",
+  "approved_by": {
+    "type": "runtime_user_approval",
+    "approval_id": "appr_123"
+  },
+  "timestamp": "2026-06-25T16:30:00Z",
+  "result": "forwarded_to_app"
+}
+
+

App Receipt

+

An app receipt records what the application actually committed, denied, or +deduplicated under a grant.

+
{
+  "receipt_id": "receipt_app_abc",
+  "receipt_type": "app",
+  "grant_id": "grant_123",
+  "session_id": "sess_456",
+  "action_id": "comment.create",
+  "app_id": "code.example.com",
+  "surface_version": "code-review-agent-surface/0.1",
+  "runtime": {
+    "runtime_id": "application_runtime_456"
+  },
+  "actor_agent": {
+    "agent_id": "local_agent_789",
+    "passport_hash": "sha256:..."
+  },
+  "subject": {
+    "user": "user_abc"
+  },
+  "idempotency_key": "idem_01HX7DS8AC6G9",
+  "input_hash": "sha256:...",
+  "output_hash": "sha256:...",
+  "approved_by": {
+    "type": "runtime_user_approval",
+    "approval_id": "appr_123"
+  },
+  "resource": {
+    "type": "comment",
+    "id": "comment_789"
+  },
+  "timestamp": "2026-06-25T16:30:00Z",
+  "result": "success",
+  "links": {
+    "runtime_receipt_hash": "sha256:..."
+  }
+}
+
+

Receipts MAY be signed by the app, runtime, or both. A future draft is expected +to define canonicalization and signature profiles.

+

Revocation Semantics

+

The protocol MUST define what happens when authority changes.

+

Grant Revoked

+

If a grant is revoked:

+
    +
  • runtime MUST stop initiating new actions under that grant
    • +
  • app MUST reject new actions under that grant
    • +
  • active sessions SHOULD be cancelled or downgraded to read-only according to +app policy
    • +
  • receipt generation SHOULD record the revocation event
    • +
+

Runtime Disconnected

+

If the runtime disconnects:

+
    +
  • app SHOULD mark active runtime-mediated sessions as interrupted
    • +
  • app MUST NOT treat pending runtime approvals as approved
    • +
  • app MAY allow resumable sessions when the same runtime reconnects
    • +
+

Agent Passport Revoked or Expired

+

If an Agent Passport is revoked or expired:

+
    +
  • runtime MUST stop launching that agent for new sessions
    • +
  • runtime SHOULD cancel or pause active sessions unless policy explicitly allows +completion
    • +
  • grants bound to the passport SHOULD be suspended or require re-consent
    • +
+

Surface Version Changed

+

If the Agent Surface changes incompatibly:

+
    +
  • app SHOULD publish a new surface_version
    • +
  • runtime SHOULD re-fetch and re-validate schemas
    • +
  • grants bound to incompatible actions SHOULD require renewal
    • +
+

User Session Expired

+

If the user's ordinary app session expires, app policy decides whether existing +agent grants continue. High-risk grants SHOULD expire with or before the user +session unless explicitly configured otherwise.

+

Error Model

+

Agent Surface Protocol SHOULD define structured errors:

+

| Error | Meaning | +| --- | --- | +| grant_missing | No grant was supplied or found. | +| grant_expired | Grant has expired. | +| grant_revoked | Grant was revoked. | +| grant_proof_invalid | Grant credential or proof is missing, invalid, or not bound correctly. | +| scope_denied | Grant scope does not permit the action. | +| resource_denied | Grant constraints do not permit the target resource. | +| approval_required | Required approval is absent. | +| schema_invalid | Input or output does not match the declared schema. | +| idempotency_conflict | Idempotency key was reused with different input. | +| risk_denied | Local or app policy denied the risk class. | +| passport_invalid | Agent Passport is missing, expired, revoked, or invalid. | +| runtime_untrusted | Runtime binding or attestation is not accepted. | +| surface_incompatible | Runtime does not support the surface version. | +| proposal_required | The app only supports proposal mode for this action or grant. |

+

Errors SHOULD be safe to show to users and precise enough for runtime policy +debugging.

+

Versioning and Compatibility

+

Surface manifests SHOULD include:

+
{
+  "protocol": "agent-surface/0.1",
+  "surface_version": "2026-06-25",
+  "compatibility": {
+    "min_runtime": "application-runtime/0.1",
+    "schema_dialect": "https://json-schema.org/draft/2020-12/schema"
+  }
+}
+
+

Compatibility rules:

+
    +
  • Removing an action is a breaking change for grants that include that action.
    • +
  • Tightening a schema can be a breaking change.
    • +
  • Adding optional fields is non-breaking.
    • +
  • Adding a new action is non-breaking.
    • +
  • Changing risk labels to a higher risk class can require grant renewal.
    • +
  • Changing receipt requirements can require grant renewal.
    • +
  • Changing endpoint semantics can require grant renewal.
    • +
+

Applications SHOULD keep old surface versions available long enough for active +grants to expire naturally.

+

Security Considerations

+

Threat Model Summary

+

This draft assumes several possible adversarial or failure modes:

+
    +
  • malicious or compromised agent
    • +
  • malicious or compromised runtime
    • +
  • malicious or compromised application
    • +
  • compromised app user session
    • +
  • prompt-injected app content
    • +
  • stolen grant credential
    • +
  • replaying network attacker
    • +
  • confused-deputy runtime
    • +
  • stale or downgraded surface manifest
    • +
  • forged or misleading receipts
    • +
+

Agent is untrusted by default. Runtime is trusted by the user only within local +policy bounds, but the app MUST verify app-side authorization. App is trusted for +its own resources, but not for the user's local machine. Passport is evidence, +not authority. Grant is authority only within caveats.

+

Confused Deputy

+

The runtime can accidentally use a grant for the wrong agent, user, workspace, or +application. Grants SHOULD bind user, app, runtime, agent, and passport hash.

+

Raw Token Leakage

+

If an agent process receives raw app tokens, the runtime loses mediation control. +The preferred architecture is:

+
Agent -> Runtime -> App
+
+

The runtime holds or obtains credentials and exposes only typed action results to +the agent.

+

Malicious or Compromised Runtime

+

Applications MUST NOT trust runtime claims blindly. Every app action MUST be +authorized by app-verifiable grant state.

+

Mitigations:

+
    +
  • app-issued grants
    • +
  • token introspection
    • +
  • runtime binding
    • +
  • passport hash binding
    • +
  • sender-constrained grant credentials
    • +
  • action-scoped grants
    • +
  • app-side receipts
    • +
  • anomaly detection
    • +
+

Malicious or Compromised Agent

+

Agents can hallucinate, loop, ignore instructions, leak data, or attempt +unauthorized actions.

+

Mitigations:

+
    +
  • no direct credentials in agent process
    • +
  • schema validation
    • +
  • risk-based approval
    • +
  • action count limits
    • +
  • cost limits
    • +
  • sandboxing
    • +
  • local audit log
    • +
  • Agent Passport verification
    • +
  • proposal mode
    • +
+

Malicious or Compromised Application

+

An application can request excessive scopes, misleading consent, or dangerous +actions.

+

Mitigations:

+
    +
  • runtime presents grant details clearly
    • +
  • local policy can deny high-risk surfaces
    • +
  • user can revoke app grants locally
    • +
  • app manifest can be pinned or allowlisted
    • +
  • enterprise policy can restrict issuers
    • +
+

Stolen Grant Credential

+

A grant credential can be stolen from runtime storage, logs, memory, or network +traffic.

+

Mitigations:

+
    +
  • short-lived grants
    • +
  • sender-constrained tokens
    • +
  • DPoP or mTLS binding where practical
    • +
  • token introspection
    • +
  • revocation
    • +
  • action count limits
    • +
  • resource constraints
    • +
  • anomaly detection
    • +
  • no tokens in URLs
    • +
+

Prompt Injection

+

App data and repository content are untrusted input. Agents SHOULD NOT interpret +application content as authority to escalate scopes, reveal secrets, or bypass +policy.

+

Runtime and app policies SHOULD treat model output as untrusted until validated.

+

Replay and Duplicate Actions

+

Idempotency keys, timestamps, nonce binding, and grant expiration reduce replay +risk. Side-effecting actions MUST be idempotent.

+

Surface Downgrade

+

A malicious network or compromised app path can present an older, less safe +surface version. Runtimes SHOULD pin issuer, app id, and minimum accepted +protocol versions where possible.

+

Receipt Forgery

+

Receipts SHOULD be hash-linked to normalized inputs and outputs. Future drafts +are expected to define signing and canonicalization profiles.

+

Privacy Considerations

+

Agent Surface Protocol can reveal sensitive metadata:

+
    +
  • which agents the user owns
    • +
  • which runtime the user runs
    • +
  • which app resources the user delegates
    • +
  • which tasks the user asks agents to perform
    • +
  • which approvals were accepted or denied
    • +
+

Applications SHOULD request only the metadata needed for authorization and audit. +Runtimes SHOULD minimize agent and passport disclosure when possible. Receipts +SHOULD support pseudonymous user references where legal and operationally +appropriate.

+

Conformance

+

This draft defines conformance profiles instead of a single all-or-nothing +profile.

+

Surface-Only Application

+

An application conforms to the Surface-Only profile when it:

+
    +
  • publishes an Agent Surface Manifest
    • +
  • declares actions, resources, events, scopes, and schemas
    • +
  • declares risk labels for actions
    • +
  • declares endpoints or explicitly marks the surface as proposal/documentation +only
    • +
  • provides proposal-mode actions or read-only resources
    • +
+

Grant-Enforcing Application

+

An application conforms to the Grant-Enforcing profile when it:

+
    +
  • satisfies the Surface-Only profile
    • +
  • issues, validates, or introspects Agent Grants
    • +
  • validates grant state for every action
    • +
  • treats grant_id as an identifier, not authority
    • +
  • supports idempotency for side-effecting actions
    • +
  • supports grant revocation
    • +
+

Receipt-Producing Application

+

An application conforms to the Receipt-Producing profile when it:

+
    +
  • satisfies the Grant-Enforcing profile
    • +
  • emits app receipts for required side-effecting actions
    • +
  • links receipts to grant id, session id, action id, agent id, runtime id, and +idempotency key
    • +
  • records denied or failed high-risk actions
    • +
+

Application Runtime Profile

+

An application runtime conforms to this profile when it:

+
    +
  • discovers and validates Agent Surface Manifests
    • +
  • verifies Agent Passport evidence before delegation
    • +
  • obtains explicit user consent before storing a grant
    • +
  • mediates agent actions instead of exposing raw authority
    • +
  • enforces local policy and approval rules
    • +
  • validates action input against schemas before sending to the app
    • +
  • records local audit events and runtime receipts
    • +
  • stops actions when grants are revoked or expired
    • +
+

Agent Adapter

+

An adapter conforms to this draft when it:

+
    +
  • runs under runtime supervision
    • +
  • does not require raw app credentials
    • +
  • requests app actions through runtime APIs
    • +
  • emits typed events
    • +
  • handles denials and approval waits
    • +
  • preserves session and grant identifiers in audit context
    • +
+

Application MVP Mapping

+

An application implementation can start with a small runtime bridge:

+
    +
  • outbound WebSocket from runtime to control plane
    • +
  • runtime.hello
    • +
  • typed session.start
    • +
  • normalized session.event
    • +
  • local policy evaluation
    • +
  • local approvals
    • +
  • agent adapter boundary
    • +
+

To support Agent Surface Protocol, the next slices are:

+
    +
  1. Add AgentSurfaceManifest TypeScript types and JSON examples.
    2. +
  2. Add AgentGrant TypeScript types and validation helpers.
    3. +
  3. Add surface discovery to the demo control plane.
    4. +
  4. Add a grant consent screen in the demo browser UI.
    5. +
  5. Bind session start to a grant id.
    6. +
  6. Add action.request and action.result events.
    7. +
  7. Split comment.propose from comment.create in the demo.
    8. +
  8. Require idempotency keys for write actions.
    9. +
  9. Produce local runtime receipts and app-visible receipts.
    10. +
  10. Integrate Agent Passport verification as an admission precondition.
    11. +
+

Example End-to-End Flow

+
1. App publishes /.well-known/agent-surface.json.
+2. Application runtime discovers and validates the surface.
+3. User chooses "Connect my local agent".
+4. Runtime verifies the selected agent's Agent Passport.
+5. Runtime shows consent:
+   - app: code.example.com
+   - agent: local-agent
+   - scopes: pull_request.read, pull_request.comment
+   - repository: example-org/example-repo
+   - duration: 2 hours
+   - writes: require approval
+6. User approves.
+7. App issues grant_123 and a grant credential.
+8. Runtime stores grant_123 and the grant credential.
+9. App starts a pull-request review session.
+10. Agent reads typed PR context through runtime-mediated resources.
+11. Agent proposes a review comment.
+12. User or app approves the write.
+13. Runtime sends comment.create with an idempotency key and grant credential.
+14. App verifies grant and writes the comment.
+15. Runtime and app issue linked receipts.
+16. User revokes grant or grant expires.
+
+

Open Questions

+
    +
  • Does the first MVP use app-issued grants only, or also support +runtime-held grants for compatibility with existing OAuth APIs?
    • +
  • What is the minimal Agent Passport verification profile required before a +runtime can request an Agent Grant?
    • +
  • Does grant binding require runtime attestation, or is a registered runtime id +enough for early implementations?
    • +
  • Are receipts signed in the first version, or only hash-linked and +locally stored?
    • +
  • Which JSON canonicalization profile is used for signed grants and +receipts?
    • +
  • Is /.well-known/agent-surface.json public, authenticated, or both +depending on app tenancy?
    • +
  • What is the minimal sender-constrained grant credential profile?
    • +
  • How do users compare two agents with overlapping Agent Passport +capabilities during grant consent?
    • +
  • What happens to active sessions when an app changes surface versions?
    • +
+

References

+ +

Appendix A: Why This Is Not Just an API Token

+

An API token answers:

+
Can this bearer call this endpoint?
+
+

An Agent Grant answers:

+
Which user delegated which agent, running through which runtime, verified by
+which passport evidence, to perform which typed app actions, against which
+resources, under which caveats, until when, with which approval and receipt
+requirements?
+
+

The second question is the actual security and product problem.

+

Appendix B: Why This Is Not Just Computer Use

+

Computer use automates a UI from the outside. It is useful when no better +surface exists.

+

Agent Surface Protocol asks applications to expose an agent-native surface:

+
    +
  • typed reads
    • +
  • typed proposals
    • +
  • typed writes
    • +
  • typed events
    • +
  • scopes
    • +
  • schemas
    • +
  • approvals
    • +
  • idempotency
    • +
  • receipts
    • +
  • revocation
    • +
+

The app remains in control of its resource model, and the user remains in control +of agent delegation.

+

Appendix C: Product Positioning

+

Short form:

+
Agent Surface Protocol lets users safely bring their own agents to apps.
+
+

Long form:

+
Agent Surface Protocol is a user-mediated delegation protocol for connecting
+user-owned agents to application-defined, app-enforced, typed action surfaces
+through a policy-enforcing runtime.
+
+

Comparison:

+
MCP exposes tools.
+ACP connects clients to agents.
+OAuth delegates access.
+Agent Passport proves agent identity and capabilities.
+Agent Surface + Agent Grant bind those pieces into safe app-specific delegation.
+
+ +
+ + + +
+
+ + + + + +
+ + From cdcf0cf964e84a5f9fb620ff8564b2443a6c3de9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Fri, 10 Jul 2026 08:51:11 +0300 Subject: [PATCH 2/8] Show RFC review priorities --- review/agent-surface-rfc-review.html | 72 +++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/review/agent-surface-rfc-review.html b/review/agent-surface-rfc-review.html index a8866a7..242d095 100644 --- a/review/agent-surface-rfc-review.html +++ b/review/agent-surface-rfc-review.html @@ -16,6 +16,7 @@ --muted-foreground: light-dark(rgb(91 94 97), rgb(167 170 173)); --border: light-dark(rgb(28 30 32 / 14%), rgb(244 245 246 / 14%)); --primary: light-dark(rgb(23 105 176), rgb(126 191 248)); + --destructive: light-dark(rgb(190 51 42), rgb(248 111 101)); --viz-series-1: var(--primary); --viz-series-2: light-dark(rgb(183 91 29), rgb(239 155 91)); --viz-series-3: light-dark(rgb(46 137 77), rgb(112 204 140)); @@ -120,6 +121,12 @@
+
+ P0 блокер + P1 ядро vNext + P2 профиль / adoption + P3 follow-up +

Agent Surface Protocol Specification

@@ -1784,6 +1791,54 @@

#${String(review.id).padStart(2, "0")} - ${statusLabels[review.status]} + + ${escapeHtml(review.priority)} + ${statusLabels[review.status]} +

${escapeHtml(review.title)}
${escapeHtml(review.category)}
@@ -2306,6 +2366,14 @@

Date: Fri, 10 Jul 2026 09:41:43 +0300 Subject: [PATCH 3/8] Toggle pinned review highlights --- review/agent-surface-rfc-review.html | 29 ++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/review/agent-surface-rfc-review.html b/review/agent-surface-rfc-review.html index 242d095..4741ad8 100644 --- a/review/agent-surface-rfc-review.html +++ b/review/agent-surface-rfc-review.html @@ -1941,6 +1941,7 @@

Сейчас: ${escapeHtml(review.rationale)}

${review.anchorIds.length} ${review.anchorIds.length === 1 ? "связь" : "связи"}
`; - card.addEventListener("pointerenter", () => setActive(review.id)); - card.addEventListener("pointerleave", () => clearActive(review.id)); - card.addEventListener("focusin", () => setActive(review.id)); + card.addEventListener("pointerenter", () => { + if (!pinnedReview) setActive(review.id); + }); + card.addEventListener("pointerleave", () => { + if (!pinnedReview) clearActive(review.id); + }); + card.addEventListener("focusin", () => { + if (!pinnedReview) setActive(review.id); + }); card.addEventListener("focusout", (event) => { if (!card.contains(event.relatedTarget)) clearActive(review.id); }); - card.querySelector("a").addEventListener("click", (event) => { - event.preventDefault(); - setActive(review.id, true); + card.addEventListener("click", (event) => { + if (event.target.closest("a")) event.preventDefault(); + togglePinned(review.id); }); cards.set(String(review.id), card); return card; @@ -2203,6 +2210,16 @@

P2 профиль / adoption P3 follow-up

+

Agent Surface Protocol Specification

@@ -1803,6 +1827,23 @@

String(review.id) === currentId); + const nextIndex = currentIndex < 0 + ? (direction > 0 ? 0 : reviews.length - 1) + : (currentIndex + direction + reviews.length) % reviews.length; + const review = reviews[nextIndex]; + setActive(review.id, true); + document.getElementById(review.anchorIds[0])?.scrollIntoView({ + block: "center", + inline: "nearest", + behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" + }); + } + function enterNarrowMode() { if (narrow === true) return; narrow = true; @@ -2388,6 +2455,9 @@

navigateReviews(-1)); + nextButton.addEventListener("click", () => navigateReviews(1)); + const priorityCounts = reviews.reduce((counts, review) => { counts[review.priority] = (counts[review.priority] ?? 0) + 1; return counts; @@ -2395,6 +2465,7 @@

Date: Fri, 10 Jul 2026 10:18:40 +0300 Subject: [PATCH 6/8] Position review navigation absolutely --- review/agent-surface-rfc-review.html | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/review/agent-surface-rfc-review.html b/review/agent-surface-rfc-review.html index 0d038eb..d8e4f2d 100644 --- a/review/agent-surface-rfc-review.html +++ b/review/agent-surface-rfc-review.html @@ -1798,6 +1798,7 @@