Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/examples.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ jobs:
# to have no upper bound. The ref is the Agent Runtimes branch that adopts the new
# SDK.
#
# Empty: Agent Runtimes 1.6.74 accepts 0.36 (personal-agent-protocol >=0.36.0,<0.37),
# so the job tests the released package.
AGENT_RUNTIMES_REF: ''
# 0.37 breaks the API: Agent Runtimes adopts it on feat/scenes (pin >=0.37.0,<0.38), so
# the job installs Agent Runtimes from that branch until a release accepts 0.37.
AGENT_RUNTIMES_REF: feat/scenes

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Expected while Agent Runtimes adopted 0.37 on feat/scenes; it now pins >=0.37.0,<0.38 and 1.6.83 is released. #19 (8b19846, 0.37.1) empties AGENT_RUNTIMES_REF, and the Examples job there builds every app with agent-runtimes 1.6.83.

steps:
- uses: actions/checkout@v6
- uses: astral-sh/setup-uv@v7
Expand Down
74 changes: 74 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,80 @@

# Changelog

## 0.37.0 (2026-11-17)

Version 1.0 **as published** (upstream `8c02b42`, frozen 2026-11-14; reviewed through
`6764732`, whose later commits restructure the site and change no normative text), the
default version, in both SDKs and both reference companies. **Breaking**: see the
[0.36 → 0.37 migration](https://personal-agent-protocol.datalayer.tech/releases/migration/#036--037).
0.4 as published is unchanged: where 1.0 changes a rule, the SDK applies it at 1.0 only.

- **Conversation protocol descriptions** (spec 3.1, 8.1, UCP 5). `AgentProtocol.description`;
`DiscoveryDocument` (`parseDiscoveryDocument`) refuses a 1.0 document whose
`agent.protocols` entry has none. `CompanyConfig.agent_description` (`agentDescription`) is
required and goes in the 1.0 document only.
- **Pushed Authorization Requests** (spec 3.2, 4.2, 4.8; RFC 9126).
`OAuthServerMetadata.require_pushed_authorization_requests`; `DirectSignInClient.begin`
pushes when given `pushed_authorization_request_endpoint` (and must when
`require_pushed_authorization_requests`), with a client assertion and a DPoP proof when
tokens are bound, and opens the authorization endpoint with `client_id` and `request_uri`
only; `link_page` and `open_link(link)` push when a link opened later is opened
(TypeScript `pushedAuthorizationRequestEndpoint`, `requirePushedAuthorizationRequests`,
`linkPage`, `openLink`). The `pap` CLI and the conformance runner push whenever the issuer
lists the endpoint. A company offers or requires it with
`CompanyConfig.pushed_authorization_requests` (`"off"`, the default, `"offered"`,
`"required"`): `POST /oauth/par`, a one-use `request_uri`, the code bound to the pushing
DPoP key.
- **Minor versions** (spec 3.4). Nothing 1.0 adds goes into a 0.4 exchange: a 0.4 document
has no description and no port, and a 0.4 Session sends no `null` context
(`context_clear_unsupported`).
- **PS384 required** (spec 4.1, 5.2, 10.7). Both reference companies accept `PS384` and
`ES256` client assertions and delegations, and now refuse RSA keys outside 2048 to 4096
bits (`RSA_KEY_BITS`).
- **Consent for scopes granted before** (spec 4.2, 4.3, 10.8, 11). Direct Sign-In requests
carry `prompt=consent` (`PROMPT_CONSENT`) unless `same_device_redirect`
(`sameDeviceRedirect`). The reference companies show their consent page for every Direct
and Device Sign-In, list every scope, and with `account_id` mark each scope
`granted_before` in `authorization_request` and `device_request`, which also give `prompt`.
- **Same DPoP key at refresh** (spec 4.4, 4.5, 4.8, 10.7). The agent keeps one DPoP key per
User ID across refreshes, as before. `CompanyConfig.bind_refresh_tokens`
(`bindRefreshTokens`) binds refresh tokens to the issuing request's key, rotated ones too:
another key is `invalid_grant`.
- **UCP scope requests** (UCP 4, 11). `ucp_scopes(profile, held, needed=, protocol_version=)`
(`ucpScopes`) requests every scope still needed at 1.0, the missing ones at 0.4; the
reference companies grant only the scopes a request names.
- **Ports in `organization.domain`** (spec 3.1, 3.2). A 1.0 domain includes its port when that
isn't 443, also in `protected_resources`; `DiscoveryClient(allow_ports=True)`
(`allowPorts`) uses such a company, refused otherwise (`port_not_allowed`). `split_domain`,
`domain_host`, `url_domain` (`splitDomain`, `domainHost`, `urlDomain`); a company serves a
domain with a port at 1.0 only.
- **Client assertion lifetime** (spec 4.1). Already the rule: the SDK's assertions last 60
seconds, at most 300, and the reference companies accept up to five minutes.
- **One sign-in for every resource** (spec 4.5, 4.7, 4.8, 7). Already so on both sides (no
`resource` at sign-in, one per token request). New: a client policy's
`allows_resource(client_id, resource)` (`allowsResource`) leaves a service out
(`invalid_target`), and `ServiceTokens` then uses it signed out.
- **Clearing context** (spec 8.4). A `context` field set to `null` clears it:
`effective_context` (`effectiveContext`), `clears_context`; the company agent's
`Turn.context` is the shared context.
- **Room to extend conversations** (spec 8.4, 8.6, 8.13). Unknown `role` reads `company`,
unknown `author.type` reads `agent` (`known_role`, `known_author_type`); the company drops
`author.id`, `name` and `image` from the agent's messages; unknown SSE event names are
skipped; an unknown conversation error code is `conversation_request_failed`, the code kept
in `details["error"]` (`KNOWN_CONVERSATION_ERRORS`, `known_conversation_error`).
- **What `working` means** (spec 8.7). Already so: the reference companies set `working`
only while replying. The docs say so.
- **Unknown sign-in errors** (spec 8.11). `ConversationEvent.error` is any string, and
`sign_in_scopes` (`signInScopes`) gives the scopes to sign in again for.
- **Mediated Sign-In retirement date**: `MEDIATED_RETIREMENT_DATE` (`2027-03-17`).
- **Scope descriptions** (spec 4.7, guides): the docs say what a good description says.
- **Open topic**: what happens to an operation in flight at sign-out is open upstream
(personal-agent-protocol#84); the open-topics page says what the reference companies do.
- **Conformance and records.** New fixture cases and a `pushed-requests` world (PAR required,
refresh tokens bound), run in all four pairings; the suite runs at 1.0 and at 0.4. The
vendored JSON Schemas are upstream's at `8c02b42`. The ledger adds the 1.0 statements
(`PAP10-*`, marked `version: '1.0'`) and marks UCP-4-06 as 0.4's.

## 0.36.1 (2026-11-16)

- **A persisted Session keeps its version** (TypeScript). `PapSession.fromJson()` restores a
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@

Python and TypeScript SDKs for the
[Personal Agent Protocol](https://personalagentprotocol.org): both implement
[version 1.0](https://personalagentprotocol.org/docs/1.0/spec) as published
(2026-11-14), the default, and
[version 0.4](https://personalagentprotocol.org/docs/0.4/spec) (2026-11-10), as
published, and its Operations extension v3, and the
[1.0 draft](https://personalagentprotocol.org/docs/spec), the default since 0.36
(0.4 is used when named in `protocol_versions`). See
published, used when named in `protocol_versions`, with the Operations extension v3. See
[Compatibility](https://personal-agent-protocol.datalayer.tech/releases/compatibility/),
[Migration](https://personal-agent-protocol.datalayer.tech/releases/migration/),
the [conformance report](https://personal-agent-protocol.datalayer.tech/protocol/conformance-report/),
Expand Down Expand Up @@ -201,7 +201,7 @@ Duplicate JSON members are rejected at Python and TypeScript trust boundaries.

## What is not implemented yet

Every flow of version 0.4 and Operations version 3 is implemented in both SDKs and
Every flow of versions 1.0 and 0.4 and Operations version 3 is implemented in both SDKs and
both reference companies: discovery, Sessions, Direct, Device and Mediated
Sign-In, refresh tokens, DPoP, OpenAPI and MCP, conversations with SSE, handoff and
close, browser sessions, feedback, and Operations. What remains:
Expand Down
4 changes: 4 additions & 0 deletions docs/docs/guides/acting-for-a-person.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ config = CompanyConfig(
name="Example Store",
domain="store.example",
scopes=("orders:read", "orders:cancel"),
# What the Company Agent can help with: agent.protocols[].description (spec 8.1).
agent_description="Your orders: tracking, changes, and cancellations",
# What a Session must hold to approve an operation.
write_scopes=("orders:cancel",),
scope_descriptions={
Expand Down Expand Up @@ -149,6 +151,8 @@ const config = new CompanyConfig({
name: 'Example Store',
domain: 'store.example',
scopes: ['orders:read', 'orders:cancel'],
// What the Company Agent can help with: agent.protocols[].description (spec 8.1).
agentDescription: 'Your orders: tracking, changes, and cancellations',
// What a Session must hold to approve an operation.
writeScopes: ['orders:cancel'],
scopeDescriptions: {
Expand Down
40 changes: 39 additions & 1 deletion docs/docs/guides/company.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ document is served at `/poppy/{version}.json`, with that `protocol_version` and
`supported_versions`. A request whose `Poppy-Version` is missing or names no served
version is refused with `version_unsupported` (HTTP 400, JSON body) where the
Session header is verified, and is never handled under another version. The
reference company speaks the 1.0 draft (`DEFAULT_PROTOCOL_VERSION`) by default;
reference company speaks 1.0 (`DEFAULT_PROTOCOL_VERSION`) by default;
another entry lets a personal agent's choice be exercised and is answered the same way.

0.4 as published (`PROTOCOL_PROFILE`) is opt-in on this side too: a company that adds
Expand Down Expand Up @@ -184,6 +184,8 @@ config = CompanyConfig(
name="Manzanita Outfitters",
domain="manzanita.example",
scopes=("orders:read", "orders:write"),
# What the Company Agent can help with, in plain language (spec 3.1, 8.1).
agent_description="Anything about your orders, returns, and our outdoor gear",
write_scopes=("orders:write",),
mediated_fields=(("email", "Email", False), ("password", "Password", True)),
# Every scope described, in words a user and a model understand (`auth.scopes`).
Expand Down Expand Up @@ -538,6 +540,40 @@ TypeScript) when:
A hosted consent page (`consent_page`) gets no binding: it protects its own
form, and `consent_decision` refuses every POST for its requests.

Every user of a personal agent shares its `client_id`, so the page lists every
scope the sign-in would grant and is shown for every request, `prompt=consent`
or not, and for every Device Sign-In, even when the account granted every scope
before (§4.2, §4.3, §10.8). A hosted page reads the request with
`authorization_request(request_id, account_id=...)` or
`device_request(user_code, account_id=...)` (`{ accountId }`): given the account
signed in on the page, each scope says `granted_before`, which the page may mark
as already granted, never hide. The request's `prompt` is there too.

### Pushed Authorization Requests and bound refresh tokens

`pushed_authorization_requests="offered"` (`pushedAuthorizationRequests`) lists
`pushed_authorization_request_endpoint` (`/oauth/par`) in the issuer's metadata,
and `"required"` also sets `require_pushed_authorization_requests`: the
authorization endpoint then takes only a `request_uri` the agent pushed with its
client assertion (RFC 9126, §4.2). A push with a DPoP proof binds the code to its
key. `bind_refresh_tokens=True` (`bindRefreshTokens`, with `dpop_binding`) binds
each refresh token, and those rotated from it, to the DPoP key of the request that
issued it: a copied refresh token is useless with another key (§4.4). Both are off
by default. A client policy may leave a service out for an agent with
`allows_resource(client_id, resource)` (`allowsResource`): its token requests are
`invalid_target` (§4.5).

### Describing the agent and the scopes

`agent_description` (`agentDescription`) is required: what the Company Agent can
help with, in plain language, published as `agent.protocols[].description` at
1.0 (§3.1, §8.1). It may say the agent can help with anything. Each scope's
description (`scope_descriptions`) is most useful when it says what the scope
unlocks, which tasks need it, and whether a task can be done without it, such as
"See your orders, returns, and bookings. Needed to track an order or find one to
change", or "Personalized search results. Not needed to search the catalog"
(§4.7; upstream guides, *Describing scopes*).

`test_guide_security.py` and `guide-security.test.mjs` test each case.

### Hosted sign-in pages
Expand All @@ -550,6 +586,7 @@ config = CompanyConfig(
name="Orders helper",
domain="orders.example",
scopes=("orders:read",),
agent_description="Your orders",
scope_descriptions={"orders:read": "See your orders"},
operations=False,
device_page="https://pap.orders.example/device?slug=orders-helper",
Expand Down Expand Up @@ -586,6 +623,7 @@ config = CompanyConfig(
name="Orders helper",
domain="orders-helper.apps.datalayer.ai",
scopes=("orders:read",),
agent_description="Your orders",
scope_descriptions={"orders:read": "See your orders"},
operations=False,
aliases=("orders.example.com",),
Expand Down
6 changes: 4 additions & 2 deletions docs/docs/guides/conversations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,10 @@ and the company sends nothing there that it cannot share with the agent.
## Where a conversation stands (§8.7)

Every read and every receipt reports the conversation's state in four fields,
each independent of the others: `working` (the company has work in progress: a
request it accepted but hasn't acted on, a reply being written), `handoff`
each independent of the others: `working` (the company is still replying: a
request it accepted but hasn't acted on, or a reply being written; since 1.0 not
work it finishes later, such as a refund that takes days, which it says in a
message and follows with another when done), `handoff`
(`pending` while it looks for a person), `responder` (`agent` or `human`), and
`closed`. A successful `POST` only means the company accepted the request, so
`working` is `true` from that moment; `ConversationClient.read_until_done`
Expand Down
29 changes: 29 additions & 0 deletions docs/docs/guides/direct-sign-in.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,35 @@ The company's page does its part: it names the personal agent that wants to
connect and tells the person to continue only if they just asked it to (see the
[company guide](/guides/company/)).

## Consent every time (§4.2, §10.8)

Every user of a personal agent shares its `client_id`, so a company that skipped
its consent page because the account had granted every scope before would let a
forwarded link get tokens with no page at all. Since 1.0 a Direct Sign-In request
carries `prompt=consent` (`PROMPT_CONSENT`): the company shows its page whatever
the account granted. `begin` adds it; pass `same_device_redirect=True`
(`sameDeviceRedirect`) only when you receive the redirect on the device that
opened the URL, where a forwarded link fails anyway.

## Pushed Authorization Requests (§4.2, RFC 9126)

When the issuer's metadata lists `pushed_authorization_request_endpoint`, pass it
to `begin` with `require_pushed_authorization_requests`, both read from the
`OAuthServerMetadata` (TypeScript `pushedAuthorizationRequestEndpoint`,
`requirePushedAuthorizationRequests`). The request is then pushed with a client assertion, and a DPoP proof when tokens
are bound, so the code is bound to the key, and the browser opens the
authorization endpoint with only `client_id` and `request_uri`. A company that
requires it takes nothing else; the protocol asks agents to push whenever it is
offered. A `request_uri` expires quickly, so a link the user opens later, such as
on their phone, goes to a page of your own: pass
`link_page="https://agent.example/sign-in/{link}"` (`linkPage`) and the browser
handoff gets that page; when it is opened, it calls `open_link(link)`
(`openLink`), which pushes the request then, and redirects to the URL it returns.

A sign-in names no `resource`: it covers every service the company offers, those
it adds later too, and each token request names one (§4.5, see
[Refresh tokens](/guides/account-tokens/)).

## TypeScript

```typescript
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/mediated-sign-in.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ company offers, or `None`.
Like OAuth's password grant, which OAuth 2.1 removes, Mediated Sign-In is a
step on the way, not where the protocol is headed. A company should offer it
only until it can add Direct or Device Sign-In, and stop once those cover the
scopes it grants. The protocol plans to remove it, on a date set when version
1.0 is published.
scopes it grants. The protocol plans to retire it on March 17, 2027
(`MEDIATED_RETIREMENT_DATE`), as version 1.0 says.

:::

Expand Down
9 changes: 6 additions & 3 deletions docs/docs/guides/personal-agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -67,12 +67,15 @@ own, and the company's domain and issuer; anything else is refused
document and `company.protocol_version` (`companyProtocolVersion(company)`) names
it.

The versions the agent implements are `DEFAULT_PROTOCOL_VERSION`, the 1.0 draft
(`DRAFT_PROTOCOL_VERSION`, `1.0`), unless you ask for others. 0.4 as published
The versions the agent implements are `DEFAULT_PROTOCOL_VERSION`, 1.0 as published
(`DRAFT_PROTOCOL_VERSION`, `1.0`, named while it was the draft), unless you ask for others. 0.4 as published
(`PROTOCOL_PROFILE`) is opt-in: `DiscoveryClient(protocol_versions=("1.0", "0.4"))`
(`discoverCompany(domain, { protocolVersions: ["1.0", "0.4"] })`) uses a company at
1.0 when it serves it and at 0.4 otherwise; `("0.4",)` alone uses only companies that
serve 0.4. Today the draft differs from 0.4 on the wire in the version string only.
serve 0.4. Where 1.0 changes a rule, the SDK follows it at 1.0 and 0.4's at 0.4: a 1.0
document must describe each conversation protocol, a domain may name a port only at 1.0
(and only with `allow_ports=True`, `allowPorts`, which uses a company on another port
for testing), and a 0.4 Session never sends a `null` context field.
`SessionClient.start(..., company=company)` names the version the company was
discovered at (`company.session_version`, `companySessionVersion(company)`) in the
Session, or pass `protocol_version` (`protocolVersion`) yourself.
Expand Down
Loading
Loading