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
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,21 @@

# Changelog

## 1.0.1 (2026-11-21)

The cases describe Poppy 1.0. In both SDKs; no change to the code, the API or the protocol
behaviour.

- **The four case decks** (`@datalayer/personal-agent-protocol/decks`), shown on the docs site
and on the Datalayer home page, said draft 0.3. Each now says `Personal Agent Protocol · 1.0 · a case` and describes its case at 1.0 as published, with version 3 of the Operations
extension: every approval says who approved, the person or the personal agent on an
instruction the person gave it, and a company may decline an agent's approval (Ledgerly
declines one for a payment, so Ada is asked about every payment); the company's consent page
is shown at every sign-in and lists every scope; a company describes its agent in a line.
- **The docs and examples** that described draft 0.3: the getting-started page, the coverage
page (Operations v3), the Two companies and Operations example decks, the Specification menu
(version 1.0), and the Pydantic AI examples' READMEs.

## 1.0.0 (2026-11-21)

The SDK's version follows Poppy's: 1.0. Poppy, the Personal Agent Protocol, reached 1.0 on
Expand Down
6 changes: 3 additions & 3 deletions docs/decks/examples/operations.deck.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@
"title": "Operations",
"subtitle": "Approve exactly what the company proposed, performed at most once, and recover a lost answer",
"meta": "Personal Agent Protocol · example",
"notes": "An operation is an action a company performs only once the user approves its exact terms: a payment, an exchange, a cancellation. This example gets Ada's approval of Northwind Bank's payments with the Operations extension, version 2."
"notes": "An operation is an action a company performs only once the user approves its exact terms: a payment, an exchange, a cancellation. This example gets Ada's approval of Northwind Bank's payments with the Operations extension, version 3."
},
{
"type": "statement",
"title": "Why operations",
"statement": "The approval is **exact** and **durable**: a chat message never approves anything.",
"notes": "Money moves only on an explicit approval of one revision of the terms. The user approves in the host's own interface, every time, and the company performs an approved action at most once, even when answers get lost."
"notes": "Money moves only on an explicit approval of one revision of the terms. Every approval says who approved; here Ada approves in the host's own interface, every time, and the company performs an approved action at most once, even when answers get lost."
},
{
"type": "mermaid",
Expand All @@ -29,7 +29,7 @@
"type": "flow",
"title": "Approval, and changed terms",
"items": [
{ "label": "1", "title": "Negotiate", "detail": "Both sides list operations version 2" },
{ "label": "1", "title": "Negotiate", "detail": "Both sides list operations version 3" },
{ "label": "2", "title": "Proposal", "detail": "An operation: EUR 1250.00 to Acme GmbH" },
{ "label": "3", "title": "Approve", "detail": "Ada approves this revision" },
{ "label": "4", "title": "New revision", "detail": "EUR 1262.50, a fee added: nothing done", "current": true }
Expand Down
2 changes: 1 addition & 1 deletion docs/decks/examples/session-transport.deck.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
"type": "mermaid",
"title": "The redirect is refused",
"diagram": "sequenceDiagram\n participant A as Agent tool\n participant H as Session client\n participant C as Company API\n A->>H: GET orders again\n H->>C: Token + JWT 3\n C-->>H: 307 to /orders/current\n H-->>A: redirect_refused",
"notes": "On the second call the company answers with a redirect. The client does not follow it: under draft 0.3 no token, Session JWT, assertion or body goes to the URL a protocol endpoint redirects to. The tool gets redirect_refused, and nothing reaches the new URL."
"notes": "On the second call the company answers with a redirect. The client does not follow it: no token, Session JWT, assertion or body goes to the URL a protocol endpoint redirects to. The tool gets redirect_refused, and nothing reaches the new URL."
},
{
"type": "bullets",
Expand Down
8 changes: 4 additions & 4 deletions docs/decks/examples/two-companies.deck.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
{
"type": "statement",
"title": "Composition, not a new protocol",
"statement": "Draft 0.3 defines **no company-to-company protocol**. Two ordinary PAP relationships, for the same user, are enough.",
"statement": "Poppy 1.0 defines **no company-to-company protocol**. Two ordinary PAP relationships, for the same user, are enough.",
"notes": "There is no special protocol between companies. Ledgerly is a company to Ada's personal agent, and, separately, a personal agent at Northwind for the same Ada, with its own client_id and keys on its own domain."
},
{
Expand All @@ -35,7 +35,7 @@
"type": "statement",
"title": "Every approval is an Operation",
"statement": "Never a chat message, and **Ada is asked about every payment**.",
"notes": "Approving money movement in a chat message would be too easy to fake or misread. In this example every approval is an Operation with a summary and terms the user approves, and draft 0.3 asks the user about each one."
"notes": "Approving money movement in a chat message would be too easy to fake or misread. In this example every approval is an Operation with a summary and terms, and says who approved. Atlas may approve on an instruction Ada gave it, but Ledgerly declines that for a payment, since it tells Northwind that Ada approved: so Ada is asked about each one."
},
{
"type": "flow",
Expand All @@ -45,14 +45,14 @@
{ "label": "2", "title": "Nothing carries over", "detail": "An approval covers one revision of one payment" },
{ "label": "3", "title": "INV-0043", "detail": "EUR 980.00: a new Operation for Ada", "current": true }
],
"notes": "Ada approves the first payment. That approval covers that revision alone: every operation Northwind returns goes to Ada, and nothing approves one in her name. So the next bill, INV-0043, is a new Operation for her to approve."
"notes": "Ada approves the first payment. That approval covers that revision alone: every operation Northwind returns goes to Ada, and an approval Atlas gives in her name is declined by Ledgerly. So the next bill, INV-0043, is a new Operation for her to approve."
},
{
"type": "mermaid",
"title": "How Ledgerly approves",
"diagram": "flowchart LR\n N[\"Northwind proposes\"] --> O[\"Operation for Ada\"]\n O -- \"Ada approves\" --> U[\"Revision and terms<br/>unchanged?\"]\n U -- \"yes\" --> C[\"Sends Northwind<br/>the approval\"]\n O -- \"Ada declines\" --> X[\"Nothing is paid\"]",
"caption": "Ledgerly approves at Northwind only the exact revision Ada approved.",
"notes": "Follow one Northwind proposal. Ledgerly proposes an Operation for Ada, which Atlas shows with its summary and terms, as it would for any company. If Ada declines, nothing is paid. When Ada approves, Ledgerly checks that Northwind's revision and terms have not changed, and only then sends Northwind the approval of that revision. Northwind's records keep the revision approved and when, and Ledgerly relays what Northwind says it came to, as written."
"notes": "Follow one Northwind proposal. Ledgerly proposes an Operation for Ada, which Atlas shows with its summary and terms, as it would for any company. If Ada declines, nothing is paid. When Ada approves, Ledgerly checks that Northwind's revision and terms have not changed, and only then sends Northwind the approval of that revision. Northwind's records keep the revision approved, that Ada approved it, and when, and Ledgerly relays what Northwind says it came to, as written."
},
{
"type": "two-columns",
Expand Down
6 changes: 4 additions & 2 deletions docs/docs/examples/cases/pap-approve-once.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ import CaseDeck from '@site/src/components/CaseDeck';

Ada's jacket isn't warm enough. Manzanita doesn't exchange it yet: it returns an
operation, its exact terms. Her agent shows them to her, and sends the same
request again only with her approval of that revision. Ada is asked about every
operation, and nothing approves in her place.
request again only with her approval of that revision. The approval says that
Ada gave it herself: at Poppy 1.0 every approval names its approver, the person
or her agent on an instruction she gave it, and the company may decline one her
agent gave.

- The wire, with new terms and a lost answer: the [Operations](/examples/operations) example flow.
- How to build it: the [Operations guide](/guides/operations/).
Expand Down
3 changes: 2 additions & 1 deletion docs/docs/examples/cases/pap-two-companies.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ import CaseDeck from '@site/src/components/CaseDeck';
Ledgerly, an accounting firm, is a company to Ada's agent, Atlas, and a personal
agent at her bank, Northwind. There is no company-to-company protocol: two
ordinary relationships meet in Ledgerly. Every payment the bank returns goes to
Ada, the first and the next, and she can't ask for that to stop.
Ada, the first and the next: an approval Atlas gives on her instruction is
declined by Ledgerly, which tells the bank that Ada approved.

The [Two companies](/examples/two-companies) example flow is this case on the
wire, with all three parties running in one process.
9 changes: 5 additions & 4 deletions docs/docs/examples/two-companies.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ import deck from '@site/decks/examples/two-companies.deck.json';

<Deck spec={deck} />

:::caution Composition, not a version 0.4 feature
:::caution Composition, not a version 1.0 feature

PAP version 0.4 defines no company-to-company protocol. This example composes
Poppy 1.0, like 0.4, defines no company-to-company protocol. This example composes
two ordinary PAP relationships for the same user. Ledgerly is a **company** to
Ada's personal agent, Atlas, and a **personal agent** at Northwind Bank for
the same Ada, with its own `client_id` and keys on its own domain.
Expand All @@ -23,8 +23,9 @@ The case [Two Companies Together](/examples/cases/pap-two-companies) tells this
story in a reader's words; this page is the same story on the wire.

Ledgerly, an accounting firm, pays Ada's supplier invoices from her Northwind
account. Every approval is an Operation, never a chat message, and Ada is asked
about every payment.
account. Every approval is an Operation, never a chat message, and says who
approved. Ledgerly declines an approval Atlas gives on an instruction, so Ada is
asked about every payment.

```mermaid
sequenceDiagram
Expand Down
5 changes: 3 additions & 2 deletions docs/docs/getting-started/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ title: Getting started
# Getting started

This quick start discovers a company, validates its declaration and OAuth
metadata, and prints the interfaces it offers. The SDKs target PAP draft 0.3
and are preview software.
metadata, and prints the interfaces it offers. The SDKs implement Poppy 1.0 as
published, the default, and 0.4 when named (see
[Compatibility](/releases/compatibility/)).

## Prerequisites

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/protocol/conformance-report.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Compatibility and conformance report

# Compatibility and conformance report

SDK version **1.0.0**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.
SDK version **1.0.1**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.

## Pairings

Expand Down
8 changes: 4 additions & 4 deletions docs/docs/protocol/coverage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ changes, applied at 1.0; one marked `(0.4)` holds at 0.4 only.
| Conversations | Create, retry idempotently, read cursor events (`cursor`, `wait` as query parameters; `conversation_id` and `events` on every read), poll or stream (`Last-Event-ID` wins), identify speakers (`role` set by the company, `author` with its `type` and, for a company's person or persona, `id`, `name`, `image`), hand off and close idempotently, sign in, stay open after sign-out. |
| Extensions | Negotiate named major versions while ignoring unsupported extensions and unknown fields. |
| Excluded tasks and feedback | Read the tasks a company doesn't offer (`excluded_tasks`, each with an optional alternative); report a missing task (`task`, `description`) with the Session header; the company answers 202, or 200 with an alternative when the task can be done after all. |
| Operations v2 | Refuse an action with 403 `approval_required` and its operation, ask the user about every operation, retry the same request with its approval, perform at most once, across interfaces, with 503 and `Retry-After` while performing. |
| Operations v3 | Refuse an action with 403 `approval_required` and its operation, ask the user (or approve on the user's instruction, the approval naming its `approver`), decline an approval, retry the same request with its approval, perform at most once, across interfaces, with 503 and `Retry-After` while performing. |

## Coverage expectations

Expand All @@ -112,19 +112,19 @@ regardless of the channel where an operation was refused.
| Mediated Sign-In | Python and TypeScript | Python and TypeScript reference companies | [Mediated Sign-In](/examples/mediated-sign-in/) |
| Refresh tokens | Python and TypeScript | Python and TypeScript reference companies | [Refresh tokens](/examples/account-tokens/) |
| Conversations: messages, events, SSE, handoff, Direct, sign-in, close | Python and TypeScript | Python and TypeScript reference companies | [Streaming](/examples/conversation-streaming/), [control](/examples/conversation-control/) |
| Operations v2 | Refuse an action with 403 `approval_required` and its operation, ask the user about every operation, retry the same request with its approval, perform at most once, across interfaces, with 503 and `Retry-After` while performing. |
| Operations v3 | Refuse an action with 403 `approval_required` and its operation, ask the user (or approve on the user's instruction, the approval naming its `approver`), decline an approval, retry the same request with its approval, perform at most once, across interfaces, with 503 and `Retry-After` while performing. |
| Web (Browser Session) | Python and TypeScript | Python and TypeScript reference companies | [Browser Session](/examples/browser-session/) |
| OpenAPI and MCP | Python and TypeScript (`ApiClient`, `McpClient`, a token by `resource`) | Python and TypeScript reference companies | [TypeScript SDK](/sdk/typescript/#openapi-and-mcp) |
| Feedback | Python and TypeScript (`FeedbackClient`) | Python and TypeScript reference companies (`POST /poppy/feedback`) | [Feedback coverage](/protocol/coverage/feedback/) |

The end-to-end journeys, [a user with a company](/examples/user-with-a-company/)
and [two companies](/examples/two-companies/) (composition, not a draft 0.3
and [two companies](/examples/two-companies/) (composition, not a 1.0
company-to-company feature), run in Python only, on the demo worlds in
`personal_agent_protocol.demo`.

## Deliberate boundaries

Draft 0.3 does not define payments, push notifications, or message
Version 1.0 does not define payments, push notifications, or message
attachments. The SDKs preserve unknown extension data but do not invent wire
formats for those areas. Company registration policy is also outside the
protocol; implementations may expose allow/block policy without presenting it
Expand Down
3 changes: 2 additions & 1 deletion docs/docs/releases/compatibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Compatibility

# Compatibility

This page is versioned with the SDK: it describes **SDK 1.0.0**.
This page is versioned with the SDK: it describes **SDK 1.0.1**.

## The PAP version implemented

Expand Down Expand Up @@ -35,6 +35,7 @@ profile, never picked up from an unattended fetch.

| SDK (PyPI and npm) | PAP profile | Specification revision | Operations | Breaking changes |
| --- | --- | --- | --- | --- |
| `1.0.1` | `0.4` | 2026-11-10 | v3 | none: the four case decks (`./decks`) and the docs describe the cases at Poppy 1.0 as published, with Operations version 3, no longer draft 0.3 |
| `1.0.0` | `0.4` | 2026-11-10 | v3 | none: the SDK's version follows Poppy's own, 1.0; the code is 0.37.5's |
| `0.37.5` | `0.4` | 2026-11-10 | v3 | none: a client that registers itself (`client_registration`) is registered as a public client whatever `token_endpoint_auth_method` it asked for among `none`, `client_secret_post`, `client_secret_basic` or none at all, and told `none`; a request that sends a client secret is refused |
| `0.37.4` | `0.4` | 2026-11-10 | v3 | none: a company may let clients that are no personal agents sign in (`public_clients`: MCP clients, with PKCE alone, verified by their client ID metadata document or registered at `/oauth/register` with `client_registration`), for tokens that work at one service and at no endpoint of the protocol; off by default |
Expand Down
2 changes: 1 addition & 1 deletion docs/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ module.exports = {
label: 'Specification',
items: [
{label: 'personalagentprotocol.org', href: 'https://personalagentprotocol.org'},
{label: 'Draft 0.3', href: 'https://personalagentprotocol.org/docs/0.3/spec'},
{label: 'Version 1.0', href: 'https://personalagentprotocol.org/docs/1.0/spec'},
{label: 'Changelog', href: 'https://personalagentprotocol.org/docs/changelog'},
{
label: 'GitHub: personal-agent-protocol',
Expand Down
4 changes: 2 additions & 2 deletions examples/pydantic-ai/conversation-control/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Conversation control

This example drives one Manzanita conversation through every control in PAP
draft 0.3 §7.9 to §7.12 with the real Python SDK: an `authorization` event
This example drives one Manzanita conversation through every control in Poppy
1.0 §8.9 to §8.12 with the real Python SDK: an `authorization` event
(`insufficient_scope`, with the scope the request needs) answered by signing
the same Session in mid-conversation (the conversation keeps its ID), a
Direct Conversation that locks its parent (`direct_conversation_open` names
Expand Down
4 changes: 2 additions & 2 deletions examples/pydantic-ai/session-transport/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

This example sends a PAP API request with the `Poppy-Session` header and a Bearer
access token, starts a new Session once after `session_ended` and resends the
request in it, refuses a redirect (draft 0.3 §3: no token or Session JWT goes to
the URL a protocol endpoint redirects to), and rejects caller-supplied
request in it, refuses a redirect (no token or Session JWT goes to the URL a
protocol endpoint redirects to), and rejects caller-supplied
authorization headers.

Access tokens, Session JWTs, and Session IDs remain host-owned.
Expand Down
6 changes: 4 additions & 2 deletions examples/pydantic-ai/two-companies/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,15 @@

Ledgerly, an accounting firm, pays Ada's invoices at Northwind Bank for her.

This is **composition**, not a company-to-company protocol: PAP draft 0.3
This is **composition**, not a company-to-company protocol: Poppy 1.0
defines none. Ledgerly is a PAP company to Atlas (Ada's personal agent) and,
for the same Ada, a PAP personal agent at Northwind with its own `client_id`
and keys. Ada connects Ledgerly to Northwind on Northwind's own page. Every
approval is an Operation: Northwind's payment is relayed to Ada as a Ledgerly
operation quoting it as written, and Ledgerly sends Northwind the approval of that
exact revision once she approves it. Ada is asked about every payment.
exact revision once she approves it. Every approval says who approved, and
Ledgerly declines an approval Atlas gives on an instruction: Ada is asked about
every payment.

The tool returns summaries as the companies wrote them and who approved each
payment. No token, code, or proof enters it.
Expand Down
Loading
Loading