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
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,13 @@ jobs:
WRANGLER_SEND_METRICS: "false"
XDG_CONFIG_HOME: ${{ runner.temp }}/pda-company-kit-04-wrangler

- name: Pinned upstream 1.0 draft Company kit and reviewed findings
if: steps.scope.outputs.specialist == 'true'
run: node scripts/check-company-kit.mjs --protocol 1.0 --reviewed-findings --output "$RUNNER_TEMP/company-kit-1.0.json"
env:
WRANGLER_SEND_METRICS: "false"
XDG_CONFIG_HOME: ${{ runner.temp }}/pda-company-kit-10-wrangler

- name: Separate DPoP-capable kit copy and independent proof controls
if: steps.scope.outputs.specialist == 'true'
run: node scripts/check-company-kit.mjs --protocol 0.4 --with-dpop --reviewed-findings --output "$RUNNER_TEMP/company-kit-dpop.json"
Expand All @@ -97,6 +104,7 @@ jobs:
name: company-kit-results
path: |
${{ runner.temp }}/company-kit-0.4.json
${{ runner.temp }}/company-kit-1.0.json
${{ runner.temp }}/company-kit-dpop.json
${{ runner.temp }}/approval-crashes.json
if-no-files-found: ignore
6 changes: 3 additions & 3 deletions .github/workflows/interop.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The interop grid: our agent against our mock Company, lenient and strict,
# The interop grid: our agent against our mock Company, lenient and strict at 1.0 and lenient at 0.4,
# and against Print with Poppy, an independent Company at a pinned commit,
# in containers behind the recording proxy (interop/).
# Docker makes it slow, so it runs on pushes to main and on pull requests
Expand Down Expand Up @@ -53,7 +53,7 @@ jobs:
- run: npm ci --legacy-peer-deps

- name: Honest agents and Companies, including injected network faults
run: npm run interop -- --agents pda --companies lenient-company,strict-company --require-supported --scenarios D,S0,N,SD,SV,SVN,SM,SMC,SX,SXV,C,CL,CC,CI,CS,CA,SO,O,OX,OU,SE,R,AO,AM,AS,RL,DP,H,DC,W,CM,ML,CDUP,CIDUP,ODUP,NREP
run: npm run interop -- --agents pda --companies lenient-company,strict-company,lenient-company-v04 --require-supported --scenarios D,S0,N,SD,SV,SVN,SM,SMC,SX,SXV,C,CL,CC,CI,CS,CA,SO,O,OX,OU,SE,R,AO,AM,AS,RL,DP,H,DC,W,CM,ML,CDUP,CIDUP,ODUP,NREP

# The lenient and strict agents too: each reads the store's documents and tokens differently.
- name: An independent Company, Print with Poppy at its pinned commit
Expand All @@ -63,7 +63,7 @@ jobs:
run: npm run interop -- --agents pda --companies evil-company --require-supported --scenarios XH,XI,BX,XB,XN,XP,XE,XR

- name: Our Companies refuse malicious agent requests
run: npm run interop -- --agents evil-personal-agent --companies lenient-company,strict-company --require-supported --scenarios YR,YD,YA,YT,YS,YK,YU,YM
run: npm run interop -- --agents evil-personal-agent --companies lenient-company,strict-company,lenient-company-v04 --require-supported --scenarios YR,YD,YA,YT,YS,YK,YU,YM

- name: Upload the grid, HAR files and container logs
if: always()
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,25 @@

Release notes and upgrade instructions for PDA. Entries are newest first, inspired by [Pi's changelog](https://pi.dev/changelog). PDA's release number is separate from the Poppy version it speaks. **Unreleased entries describe repository changes, not a deployed release.**

## Unreleased — the 1.0 draft beside 0.4

The agent, the mock Company and the validator speak the 1.0 draft retrieved on 13 November at 15:48 UTC (upstream `bb98332`) beside 0.4 ([decision 51](docs/decisions.md#51-10-beside-04)). The [1.0 upgrade](docs/poppy-1.0-upgrade.md) gives each of its 15 changelog entries a disposition.

**On upgrade:** a Company that offers 1.0 is used at 1.0 from its next request: the Session restarts with the new declaration and keeps its account, and an open conversation keeps the version it started in (8.2). The new `poppy_dpop_keys` and `poppy_dpop_nonces` tables are created on first use. Keys held in memory before the update are lost with the restart, so each issuer's first refresh afterwards uses a new key, which is then stored; no live Company binds refresh tokens to a key yet.

- `PROTOCOL_VERSIONS` is `0.4` and `1.0`. Discovery uses the newest version a Company offers that is compatible with one the agent speaks. From 1.0 a newer minor version is compatible, so a Company serving 1.1 is used as 1.0, and every request declares `Poppy-Version: 1.0`.
- Under 1.0 each `agent.protocols` entry needs a `description`, and discovery refuses a 1.0 Company without one. `poppy_discover` gives the model the description, to choose between the Company's agent and its APIs.
- When an issuer lists `pushed_authorization_request_endpoint`, under either version, the Direct Sign-In card links to the agent's new `/poppy/sign-in` page. Opening it pushes the request with the client assertion and a DPoP proof, then redirects to the authorization endpoint with only `client_id` and `request_uri`. A browser not signed in to PDA is asked to sign in first, and nothing is pushed.
- DPoP keys are stored, sealed, by issuer and User ID, so a refresh after a restart or eviction uses the key the refresh token was issued with (1.0 4.4). The latest nonce from each server is stored too, so those proofs keep carrying it. Both tables are withheld from the data export.
- Direct Sign-In requests to a 1.x Company carry `prompt=consent`, so the Company shows its consent page even for scopes the account granted before (1.0 4.2, 10.8).
- A conversation message with a `role` the agent doesn't know is relayed as the Company's content, where it was dropped. In a 1.x conversation, a stream event with an SSE name the agent doesn't know is skipped (1.0 8.4, 8.6).
- `poppy_discover` tells the model that a Company's name comes from its own `poppy.json`, and to show the User the domain with it when unsure (1.0 10.3 and its guides).
- Fixed: the Worker forwarded `/poppy/*` requests to the person's agent with `redirect: "follow"`, so a redirect from the agent would have been followed inside the Worker rather than reaching the browser. The callback never redirected; the new sign-in page does.
- The validator has a 1.0 profile: 0.4's rules with the required descriptions (`protocol-description-empty`), a port other than 443 allowed in `organization.domain`, and ES256 and PS384 required in an issuer's listed client-assertion algorithms (`metadata-assertion-algs`). Under both versions it checks the PAR endpoint is HTTPS and reports `require_pushed_authorization_requests` without it (`par-endpoint-missing`). A newer 1.x document is checked with the 1.0 profile and noted (`version-newer-minor`).
- The mock serves 1.0 and 1.1, describes its protocols under 1.x, can offer or require PAR (`pushedAuthorization`), bind refresh tokens to their key (`bindRefreshTokens`) and stream an event a later version might add (`laterStreamEvent`). Under 1.x it takes a `context` field set to `null` as cleared. New checks: `authorize.prompt-consent`, `par.not-pushed`, `par.extra-parameters`, `par.code-key` and `dpop.refresh-key-changed`.
- The 1.0 snapshot, kit and requirement ledger are pinned in `spec/`. CI runs the 1.0 kit against the mock with [reviewed findings](test/company-kit/reviewed-findings-1.0.json), the same as the 0.4 kit's. Each request the agent sends is checked against the schemas of the kit for the version it declares.
- The Python Hypothesis client speaks 1.0 beside 0.4, and each run draws the version the mock serves, PAR and bound refresh tokens. The interop grid's `lenient-company` and `strict-company` serve 1.0, and a new `lenient-company-v04` keeps 0.4 in CI.

## Unreleased — asking to contact a Company, amounts in cents, and checkout links that aren't ready

- When the User's request names a Company they haven't selected, the agent asks on a card with the domain, the Company's own name and the photos it would send. **Allow** sends a message from the composer that selects them; the card grants nothing itself, only a run the User started can ask, and a domain without a `poppy.json` the agent can use gets no card ([decision 50](docs/decisions.md#50-the-agent-can-ask-to-contact-a-company)). Its tool line reads "Asked you to let your agent contact shop.example", and `scripts/app-smoke.mjs --company-access-journey` follows it in Chromium from the card to the Company's terms.
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@

**A Personal Agent for [Poppy](https://personalagentprotocol.org/), the Personal Agent Protocol, built alongside the tools we used to test it: a validator, a strict mock Company, an interop harness, and written-up spec issues for each draft.** It is for the draft's authors and for people implementing either side of the protocol.

Poppy is a draft standard. PDA speaks **0.4 alone**, the 1.0 release candidate published on 10 November 2026 and retrieved on 11 November; it dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)) ([changelog](CHANGELOG.md), [upgrade procedure](docs/upgrading.md)). This project's agent runs on Cloudflare Workers with one Durable Object per person and Claude Sonnet 5.5 through Pi. It finds a Company that publishes `poppy.json`, names a Session on every request with a signed `Poppy-Session` header, has you sign in on the Company's own page when it needs your account, talks to the Company's agent, calls its APIs, and asks you on the page when the Company returns an operation for approval. The status is alpha. At 0.1 and 0.2 the deployed agent signed in and out at one live Company, Alpine Retail, a colleague's test store (13 and 14 October), and got as far as asking to upload a photo at print-with-poppy's live store (12 October) ([live evidence](docs/history/live-0.2-testing.md)). The [current verification report](docs/poppy-0.4-conformance.md#current-verification) records the 0.4 checks and live limits; the [0.3 review](docs/poppy-0.3-conformance.md) keeps 0.3's independent demo evidence.
Poppy is a draft standard. PDA speaks **0.4**, the 1.0 release candidate published on 10 November 2026 and retrieved on 11 November, and beside it the **1.0 draft** retrieved on 13 November ([decision 51](docs/decisions.md#51-10-beside-04), not yet deployed); it dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)) ([changelog](CHANGELOG.md), [upgrade procedure](docs/upgrading.md)). This project's agent runs on Cloudflare Workers with one Durable Object per person and Claude Sonnet 5.5 through Pi. It finds a Company that publishes `poppy.json`, names a Session on every request with a signed `Poppy-Session` header, has you sign in on the Company's own page when it needs your account, talks to the Company's agent, calls its APIs, and asks you on the page when the Company returns an operation for approval. The status is alpha. At 0.1 and 0.2 the deployed agent signed in and out at one live Company, Alpine Retail, a colleague's test store (13 and 14 October), and got as far as asking to upload a photo at print-with-poppy's live store (12 October) ([live evidence](docs/history/live-0.2-testing.md)). The [current verification report](docs/poppy-0.4-conformance.md#current-verification) records the 0.4 checks and live limits; the [0.3 review](docs/poppy-0.3-conformance.md) keeps 0.3's independent demo evidence.

## Components and supported Poppy versions

The implementation follows the text retrieved on **11 November 2026**, matching upstream commit `ed47408` ([snapshot](spec/draft-0.4-retrieved-2026-11-11/README.md)). [spec/upstream.json](spec/upstream.json) pins the snapshot and its hashes; `npm run spec:drift` reports later changes. The [conformance review](docs/poppy-0.4-conformance.md) distinguishes implementation, independent checks and live verification. The requirement ledger does not certify full conformance.
The implementation follows the 0.4 text retrieved on **11 November 2026**, matching upstream commit `ed47408` ([snapshot](spec/draft-0.4-retrieved-2026-11-11/README.md)), and the 1.0 draft retrieved on **13 November 2026**, at `bb98332` ([snapshot](spec/draft-1.0-retrieved-2026-11-13/README.md)). [spec/upstream.json](spec/upstream.json) pins the snapshot and its hashes; `npm run spec:drift` reports later changes. The [conformance review](docs/poppy-0.4-conformance.md) distinguishes implementation, independent checks and live verification. The requirement ledger does not certify full conformance.

| Component | Poppy versions | What it does |
| --- | --- | --- |
| [PDA application and client](pda-spec.md) | 0.4 | Signs in to Companies, uses their APIs, conversations and websites, and asks for approval of the Company's exact terms when it returns an operation (Operations 3), unless a standing instruction you wrote covers them; selected task photos upload without another permission click; unselected files need disclosure consent |
| [Document validator](docs/validator.md) | 0.4 | Checks Company discovery, OAuth and protected resource metadata, client metadata and keys. One library backs the web form, HTTP API and CLI |
| [Reference/mock Company](interop/README.md#the-fake-implementations) | 0.4 | Serves Company endpoints and records violations. Tests select lenient, strict, deliberately flawed or adversarial behavior |
| [PDA application and client](pda-spec.md) | 0.4, 1.0 | Signs in to Companies, uses their APIs, conversations and websites, and asks for approval of the Company's exact terms when it returns an operation (Operations 3), unless a standing instruction you wrote covers them; selected task photos upload without another permission click; unselected files need disclosure consent |
| [Document validator](docs/validator.md) | 0.4, 1.0 | Checks Company discovery, OAuth and protected resource metadata, client metadata and keys. One library backs the web form, HTTP API and CLI |
| [Reference/mock Company](interop/README.md#the-fake-implementations) | 0.4, 1.0 | Serves Company endpoints and records violations. Tests select lenient, strict, deliberately flawed or adversarial behavior |
| [Fake test Personal Agents](interop/README.md#the-fake-implementations) | 0.4 | Exercise Companies with lenient, strict or sloppy behavior; the restored malicious agent sends mutated 0.4 requests to our own mocks |
| [Interop harness](docs/interop-spec.md) | 0.4 | Runs agent/Company pairs in isolated containers, records exchanges and reports failures by protocol rule. Its 0.1 and 0.2 peers and lanes are retired ([§14](docs/interop-spec.md#14-retired-with-01-and-02)), and its 0.3 pairing with print-with-poppy ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)) |
| Independent client tests | 0.4 | A [Python client and Hypothesis model](test/hypothesis/README.md) of the mock, written apart from `src/poppy` so a misreading both share can show |
| [Specification snapshots and the requirement ledger](docs/poppy-0.4-upgrade.md) | 0.4 | Preserve upstream text, and give each of 0.4's changelog entries a disposition with its code and evidence; [0.3's](docs/poppy-0.3-upgrade.md) are kept as history |
| Specification snapshots and the requirement ledgers ([0.4](docs/poppy-0.4-upgrade.md), [1.0](docs/poppy-1.0-upgrade.md)) | 0.4, 1.0 | Preserve upstream text, and give each changelog entry a disposition with its code and evidence; [0.3's](docs/poppy-0.3-upgrade.md) are kept as history |

PDA uses the document validator during discovery, and the fake agents wrap PDA's client. The [ecosystem map](docs/ecosystem.md#current-ecosystem) records observation dates and tested revisions separately for source reviews, grids and live journeys.

Expand Down
Loading