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

# Changelog

## 0.37.3 (2026-11-18)

A company's services at URLs of their own. In both SDKs; additive API only, and a company that
names none behaves exactly as before.

- **`resource_servers` (`resourceServers`) on `CompanyConfig`** (spec 3.2, 4.5, 7). The SDK's
company issued a token for one MCP `resource`, its own `https://{domain}/mcp`, and listed only
that in `protected_resources`. A company whose MCP server answers on another host than its
issuer's (`https://mcp.example.com/mcp`) had no way to offer it signed in: a Personal Agent
that asked for a token with `resource` set to the server's `url`, as section 7 requires, got
`invalid_target`. Each URL named here is listed in the issuer's `protected_resources` and gets
Bearer tokens issued for it, at the request that completes a sign-in or at refresh (RFC 8707),
subject to the client policy's `allows_resource` like every other service. A sign-in that
named no `resource` covers them, those added after it too (4.5).
- **`CompanyService.access_token_for(token, resource)` (`accessTokenFor`)**: for such a service
to verify what it is sent. The token's record when it was issued for that service, is
unexpired, its sign-in has not ended, its scopes are still offered and the client policy
still allows its agent and this service for it (asked when the token is presented, so a
blocked agent's token stops working at once); nothing otherwise, the
default token and a token for another service among them (4.5: a token issued for a
`resource` is accepted only at that service). The service enforces the record's `scopes`.
- **`resource_metadata_url(resource)` (`resourceMetadataUrl`)**: where a service's protected
resource metadata is (RFC 9728 §3.1), for the `resource_metadata` of its challenges (7). It
is the helper discovery reads the metadata at (`protected_resource_metadata_url`,
`protectedResourceMetadataUrl`), so what a service publishes and what a Personal Agent fetches
agree, a trailing slash on the `url` included.
- Each resource server is checked when the company is configured, with the rule the issuer's
metadata is read with (HTTPS, a host, no user information), since each is published in
`protected_resources` and one entry a Personal Agent refuses would fail discovery for the
whole company. Narrowed to what names one service: a well-formed host in small ASCII letters
(an internationalized name as its A-labels, a port allowed), no query, no fragment, named
once, and not one of the company's own (`https://{domain}`, an alias, its `/mcp`, its
conversation endpoint); a company with no issuer has none. A service named here gets Bearer
tokens even from an issuer that binds its own with DPoP (7: a company whose MCP server
doesn't accept DPoP returns Bearer tokens for it).

## 0.37.2 (2026-11-17)

Fixes from the review of 0.37.1, and what a host needs to push a Direct Sign-In whose redirect
Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,8 +227,9 @@ Each open or partial requirement is listed with its reason in
recovery fixture across the four pairings (a Python or TypeScript personal
agent against a Python or TypeScript reference company), over real TCP and
TLS: [Compatibility and conformance report](https://personal-agent-protocol.datalayer.tech/protocol/conformance-report/).
- **An independent study**: in November 2026 an independent tester ran the
Python SDK 0.35.0, self-hosted and unmodified, through Poppy 1.0's Operations
- **An independent study**: in November 2026
[Kai Karlstrom](https://github.com/kkrlstrm/kirkaldy-conformance-kit) (Kirkaldy, independent testing of agent infrastructure)
ran the Python SDK 0.35.0, self-hosted and unmodified, through Poppy 1.0's Operations
extension and sign-out tests, with effects counted by a separate recorder.
Everything passed: a retry after a lost response returned the original
response and performed the action once (3 of 3 trials; a deliberately broken
Expand All @@ -239,7 +240,9 @@ Each open or partial requirement is listed with its reason in
user's approval, instruction coverage). One finding is about the protocol, not
the SDK: an operation already performing at sign-out completed and reported
success, which Poppy leaves unspecified (raised on the Poppy tracker, #84).
0.36.x was not tested. The write-up, evidence and harness:
0.36.x and later versions were not tested; a re-run on the current release
is planned, and its result will be published. The write-up, evidence and
harness:
[studies/poppy-1.0](https://github.com/kkrlstrm/kirkaldy-conformance-kit/tree/main/studies/poppy-1.0).
- **The official company kit**: validate a company implementation, on these
SDKs or any other, with the protocol's
Expand Down
54 changes: 54 additions & 0 deletions docs/docs/guides/company.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,10 @@ implements, of version 0.4 and Operations version 3:
`resource`); the endpoint takes only those, answering the default token with
`invalid_token` and `resource_metadata`, and a signed-out request with the
Session header alone. Session JWT audiences and User IDs stay the company's;
- with `resource_servers` (`resourceServers`), the company's services at URLs of
their own, such as an MCP server on another host than the issuer's
(`https://mcp.example.com/mcp`): see [A service at a URL of its
own](#a-service-at-a-url-of-its-own);
- Bearer access tokens, or tokens bound with DPoP (`dpop_binding`, in TypeScript
`dpopBinding`: `off` by default, `optional` binds when a proof comes, `required`
refuses a token request with none; `dpop_nonces`, `dpopNonces`, asks for server
Expand Down Expand Up @@ -638,6 +642,56 @@ same issuer: one company, never a second identity. Every endpoint stays on
`/.well-known/poppy.json` answers `404 not_found`. An alias is a DNS name in
small letters, another than `domain`, named once.

### A service at a URL of its own

The reference company serves its MCP server at `https://{domain}/mcp`, on the
issuer's own host. A company whose MCP server answers elsewhere, such as
`https://mcp.example.com/mcp` beside an issuer at `https://example.com`, names it
in `resource_servers` (`resourceServers`):

```python
from personal_agent_protocol.company import resource_metadata_url

config = CompanyConfig(
name="Example",
domain="example.com",
scopes=("orders:read",),
agent_description="Your orders",
scope_descriptions={"orders:read": "See your orders"},
operations=False,
resource_servers=("https://mcp.example.com/mcp",),
)
print(resource_metadata_url(config.resource_servers[0]))
```

The URL is the server's `url` as `poppy.json` lists it in `apis`, since that is the
`resource` a Personal Agent asks a token for (§7). For each one:

- the issuer's metadata lists it in `protected_resources`, after `https://{domain}`
(§3.2: it MAY list other resources, such as the Company's MCP servers);
- the token endpoint issues a token for it when a request names it as `resource`,
the request that completes a sign-in or a refresh (§4.5, RFC 8707). A sign-in that
named no `resource` covers it, a service added after the sign-in too. Any other
`resource` is still `invalid_target`, and the client policy's `allows_resource`
can leave a service out for an agent;
- the token is a Bearer token, even when the issuer binds its own with DPoP (§7: a
Company whose MCP server doesn't accept DPoP returns Bearer tokens for it).

The service does its own half (§7). It publishes protected resource metadata whose
`resource` equals its `url` and whose `authorization_servers` includes the company's
issuer, at `resource_metadata_url(url)` (`resourceMetadataUrl`, RFC 9728 §3.1), which
the example prints. It verifies each token it is sent with
`await service.access_token_for(token, url)` (`accessTokenFor`), which answers the
token's record only when it was issued for that service, is unexpired, its sign-in
has not ended and its scopes are still offered. The default token and a token for
another service answer `None` (`undefined`): the Company accepts a token issued for
a `resource` only at that service (§4.5), and a service that gets a token not issued
for it returns `invalid_token` with `resource_metadata` in its challenge. The
record's `account_id`, `client_id` and `scopes` are what the service acts on, and it
enforces the scopes on every call.

A company that names no resource server behaves as before.

### Before production

The defaults keep state in one process. A deployment contributes a durable
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 **0.37.2**, 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 **0.37.3**, 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: 5 additions & 3 deletions docs/docs/protocol/independent-testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ their own implementation.

## An independent study of the Python SDK 0.35.0

In November 2026 an independent tester of agent infrastructure ran the
**Python SDK 0.35.0, self-hosted and unmodified**, through tests of Poppy 1.0's
In November 2026
[Kai Karlstrom](https://github.com/kkrlstrm/kirkaldy-conformance-kit) (Kirkaldy, independent testing of agent infrastructure)
ran the **Python SDK 0.35.0, self-hosted and unmodified**, through tests of Poppy 1.0's
**Operations extension** and **sign-out**. The effects of each test were counted
by a separate recorder, not read from the SDK's own responses.

Expand All @@ -31,7 +32,8 @@ Poppy does not say what should happen in that case; it was raised on the Poppy
tracker (issue #84).

**What it does not cover:** the study tested 0.35.0. Version 0.36.x (the 1.0
draft as the default) has not been tested by it.
draft as the default) and later versions have not been tested by it. A re-run
on the current release is planned, and its result will be published.

The write-up, its evidence and the harness are published:
[studies/poppy-1.0](https://github.com/kkrlstrm/kirkaldy-conformance-kit/tree/main/studies/poppy-1.0).
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 0.37.2**.
This page is versioned with the SDK: it describes **SDK 0.37.3**.

## 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 |
| --- | --- | --- | --- | --- |
| `0.37.3` | `0.4` | 2026-11-10 | v3 | none: a company names its services at URLs of their own (`resource_servers`, an MCP server on another host), which its issuer lists in `protected_resources` and issues Bearer tokens for, and which verify them with `access_token_for` |
| `0.37.2` | `0.4` | 2026-11-10 | v3 | none: opening a sign-in link reads its record without consuming it (the state store's optional `get`), a link begun by 0.37.0 still opens after an upgrade, and the Direct Sign-In start names its `state` for hosts whose redirect lands elsewhere |
| `0.37.1` | `0.4` | 2026-11-10 | v3 | none: a bound refresh token keeps its sign-in at a Bearer-only MCP server, `open_link` leaves the callback state to `complete`, an empty SSE event name is a message, and `effectiveContext` keeps a `__proto__` field as a field |
| `0.37.0` | `0.4` | 2026-11-10 | v3 | [0.36 → 0.37](/releases/migration/#036--037): 1.0 as published (`8c02b42`): required conversation protocol descriptions (`agent_description`), Pushed Authorization Requests, `prompt=consent`, refresh tokens bound to their DPoP key, ports in `organization.domain`, one sign-in for every resource, and unknown values read safely |
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@datalayer/personal-agent-protocol",
"version": "0.37.2",
"version": "0.37.3",
"description": "TypeScript SDK for Personal Agent Protocol 0.4 (2026-11-10) and its Operations extension v3",
"repository": {
"type": "git",
Expand Down
19 changes: 19 additions & 0 deletions personal_agent_protocol/__tests__/test_docs_examples.py
Original file line number Diff line number Diff line change
Expand Up @@ -788,6 +788,25 @@ async def check(namespace: dict[str, Any], out: str) -> None:
return {"CompanyConfig": CompanyConfig}, check


@case("docs/docs/guides/company.mdx#4")
async def _resource_servers(docs: Docs) -> tuple[dict[str, Any], Check]:
async def check(namespace: dict[str, Any], out: str) -> None:
import httpx

from personal_agent_protocol.company import build_company

config = namespace["config"]
assert out.strip() == "https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
async with httpx.AsyncClient() as http:
service = build_company(config, http_client=http)
assert service.oauth_metadata()["protected_resources"] == [
"https://example.com",
"https://mcp.example.com/mcp",
]

return {"CompanyConfig": CompanyConfig}, check


# CLI and extensions -----------------------------------------------------------------------


Expand Down
Loading
Loading