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
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,19 @@ Protocol baseline: **0.3, the text retrieved on 29 October 2026** ([snapshot](sp
- The interop agent reads pages in Node with `html-rewriter-wasm` (lol-html, as Workers' `HTMLRewriter`), so browsing scenarios see the page the Company served.
- An ecosystem refresh for 29 October: who implements the 28 October text, and dated public discovery results ([ecosystem.md](docs/ecosystem.md), [evidence](docs/evidence/ecosystem-2026-10-29/README.md)).

### Changed

- Task API requests and MCP calls now run before the Company asks for approval of its exact terms. The preliminary per-write card is removed; photos still need disclosure consent and website forms still need approval. This replaces decisions 36/37's blanket confirmation policy ([decision 38](docs/decisions.md#38-task-requests-use-the-companys-approval-boundary)).

### Fixed

- Pending Company terms no longer wake the model to recreate the request. Fresh calls reuse matching pending terms, and tool replay returns the recorded outcome without another write. Internal dispatch records stay out of approval cards, including after reconciliation and receipt expiry.
- Approved API/MCP results are kept whole instead of cut at 2,000 characters. Successful result URL/link fields are delivered directly as HTTPS links with their destinations labelled, including signed query strings. Links in operation summaries remain inert. The reported live checkout link's exact failure is not established by diagnostics that omit bodies and URLs.
- Every coalesced task call retains its durable identity after settlement, decline and revisions. Fresh attempts get immutable decision IDs; late clicks cannot approve them. Returned terms keep the transport's authority, and committed pending terms are republished after interrupted card delivery. A changed MCP read-only annotation cannot bypass a stored result.
- Approval storage is version 3 only: no old two-card flow, migration or missing-authority defaults. Older pending forms are refused and must be requested afresh; uncertain historical outcomes remain held.
- Activity exports diagnostics by action, retaining safe event copies separately from general pruning (50 flows, 200 events/256 KiB each). Closed link-rejection reasons and client-reported source/anchor equality are counts only; no URL values or hashes enter reports. Shared unit context and missing pruned history are disclosed.
- Turn diagnostics wait for in-flight tools before emitting, without blocking later runs. A deterministic failing reproduction established this lifetime race; it does not establish the cause of the earlier CI foreign-text assertion.
- Crash verification now has 16 actual process-group SIGKILL cases, including initial dispatch, interrupted terms publication, real Pi MCP result settlement and an unsafe replay negative control.
- A delayed refresh or retry response can no longer overwrite newer sign-in access, undo sign-out or restart a newer Session. Browser cookies and saved forms are invalidated when consent scopes or the account family change.
- Approval receipt failures preserve completed Company outcomes. Reconciliation and batch notifications keep their ID/text across failure and restart, and a batch acknowledges only decisions it actually claimed.
- Conversation streams handle CRLF split across chunks, bound individual events and unfinished text, cancel cleanly and release read timers. Concurrent feedback reports no longer duplicate a task or combine different Users in the mock's repetition oracle.
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The implementation follows the text retrieved on **29 October 2026** ([snapshot]

| Component | Poppy versions | What it does |
| --- | --- | --- |
| [PDA application and client](pda-spec.md) | 0.3 | Signs in to Companies, uses their APIs and conversations, and asks for approval before account changes, then for the Company's terms when it asks (Operations 2) |
| [PDA application and client](pda-spec.md) | 0.3 | Signs in to Companies, uses their APIs and conversations, and asks for approval of the Company's exact terms when it returns an operation (Operations 2); file uploads retain separate disclosure consent |
| [Document validator](docs/validator.md) | 0.3 | 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.3 | 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.3 | Exercise Companies with lenient, strict or sloppy behavior; the restored malicious agent sends mutated 0.3 requests to our own mocks |
Expand Down
10 changes: 5 additions & 5 deletions docs/capabilities.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# What the agent can do, and where each part comes from

The [README](../README.md#what-you-can-do-with-it) says what a person can ask for. This page maps each capability to its source: a Poppy feature, with the section of [Draft 0.3](../spec/draft-0.3-retrieved-2026-10-28/README.md) (28 October text), the Operations extension (Ops, version 2) or the Mediated Sign-In extension (MSI) it implements, or a feature of this project. Each model tool is listed once, beside the feature it serves, with what needs the User's approval and the file that defines it. How each part works is in the [spec](../pda-spec.md); why it was built that way is in [decisions.md](decisions.md).
The [README](../README.md#what-you-can-do-with-it) says what a person can ask for. This page maps each capability to its source: a Poppy feature, with the section of [Draft 0.3](../spec/draft-0.3-retrieved-2026-10-29/README.md) (29 October text), the Operations extension (Ops, version 2) or the Mediated Sign-In extension (MSI) it implements, or a feature of this project. Each model tool is listed once, beside the feature it serves, with what needs the User's approval and the file that defines it. How each part works is in the [spec](../pda-spec.md); why it was built that way is in [decisions.md](decisions.md).

Back to the [README](../README.md)

Expand All @@ -19,8 +19,8 @@ Some things look like they could be tools but are features of the agent or the p

Two kinds of approval card exist, and they come from different places:

- **A Company's proposal is Poppy's.** When a Company has the Operations extension and answers a write with an operation (Ops §4), the User approves its exact revision and terms on a card (Ops §5.1), and only then does the agent confirm it (Ops §5.2). Generic standing approval is paused; every new operation uses the User's exact-revision card. This is the only approval a Company ever sees.
- **Our own cards are this project's.** Every write a Company doesn't propose waits on a local approval card before anything is sent: an OpenAPI write whose description doesn't declare an operation, an MCP tool without `readOnlyHint: true`, and a website form submit. Every upload of the User's photo waits on one too, even to an endpoint that proposes. The draft doesn't ask for these; we add them so that nothing changes the User's account, and none of their files leaves, on the model's word alone ([decision 6](decisions.md#6-prompt-injection-defences-that-are-structural), [decision 26](decisions.md#26-photos-in-the-chat-uploaded-only-with-the-users-approval)). Once approved, the card's receipt says what the Company answered: done for a 2xx; sent as approved but answered with that status and error code, so nothing changed unless the Company says otherwise; or, with no answer, that it may or may not have reached the Company.
- **The Company's operation is Poppy's.** Send the task request first. When the Company returns an operation (Ops §4), show its exact summary and obtain the User's decision (Ops §5), then resend the stored request with that revision's approval (Ops §6). The Company chooses which actions need confirmation. A pending operation does not start another model turn or require the model to rebuild the request.
- **Our own cards protect file disclosure and form submission.** A photo leaves only after the User approves sending it to that Company. Website forms still show their exact submission before sending. There is no compatibility path for older preliminary write cards: their stored forms are refused; current API tasks do not get that card ([decision 38](decisions.md#38-task-requests-use-the-companys-approval-boundary)). Lost or unreadable answers remain uncertain; a new approval cannot bypass their hold.
- **Some writes get no card at all.** A write the Company's description leaves outside its Poppy Session (its own sign-in, session, token or compatibility endpoint) is refused before any card: the agent's only access is its Poppy Session ([readings.md](readings.md#poppy-session-only)).

No tool approves anything. A scheduled task's run is a background turn like a Company message's, so the same holds for it: it can ask for approval, never give it. Approving, declining, entering credentials, signing out and speaking in a Direct Conversation are actions on the page.
Expand All @@ -35,8 +35,8 @@ No tool approves anything. A scheduled task's run is a background turn like a Co
| Sign in at the Company when a task needs the User's account: Direct, Device or Mediated Sign-In, reusing a refresh token that covers the scopes, the Company's scopes described with their hints | §4.2–4.4, §4.7, §5.4, MSI | `poppy_sign_in` | Yes: the User signs in on the Company's page or on the card; the tool never takes a password | `src/poppy/signin.ts` |
| Sign out of a Company | §4.6, §5.5 | None: the Companies page | It is the User's action | `src/poppy/signout.ts` |
| Browse the Company's website in the Session, with no JavaScript, after joining the browser to it | §6 | `poppy_browse` | A form submit waits for our own card | `src/poppy/browser.ts`, `src/poppy/fetch-browser.ts` |
| Look things up and make changes through the Company's OpenAPI API, including uploading the User's photo | §7 | `poppy_api_describe`, `poppy_api_call` (a JSON body as `body`, an object, or `bodyValue`, anything else) | Reads: no. Every write and every upload: our own card first, then, when the Company answers `approval_required`, its terms on a card of their own (Ops §4–6). A write outside the Poppy Session: never made | `src/poppy/apis.ts`, `src/poppy/operations-v2.ts` |
| Use the Company's MCP tools | §7 | `poppy_mcp_list`, `poppy_mcp_call` (`args` checked against the tool's `inputSchema` first) | A tool without `readOnlyHint: true`: our own card, then the Company's terms when its result asks for approval (Ops §4) | `src/poppy/apis.ts` |
| Look things up and make changes through the Company's OpenAPI API, including uploading the User's photo | §7 | `poppy_api_describe`, `poppy_api_call` (a JSON body as `body`, an object, or `bodyValue`, anything else) | Only when the Company returns `approval_required`, on its exact-terms card (Ops §4–6). Uploads separately ask for file disclosure consent. A write outside the Poppy Session: never made | `src/poppy/apis.ts`, `src/poppy/operations-v2.ts` |
| Use the Company's MCP tools | §7 | `poppy_mcp_list`, `poppy_mcp_call` (`args` checked against the tool's `inputSchema` first) | When the result returns an operation, its exact terms wait on a card (Ops §4–6) | `src/poppy/apis.ts` |
| Talk to the Company's agent, with replies read in the background or streamed | §8.1–8.8 | `poppy_message`, `poppy_read` | No: a message never authorizes an account action. A Company Agent's operation waits on a terms card | `src/poppy/conversations.ts` |
| Ask for a person at the Company | §8.9 | `poppy_handoff` | No | `src/poppy/conversations.ts` |
| Let the User talk to the Company directly | §8.10 | `poppy_invite_user` | Yes: the User decides whether to start it, and writes their own messages | `src/poppy/conversations.ts`, `src/poppy-ui.tsx` |
Expand Down
17 changes: 16 additions & 1 deletion docs/decisions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Architecture and decisions

Why the Poppy Demo Agent is built the way it is. The [spec](../pda-spec.md) says what is built and how; this file records the choices behind it, as decision records: the context, the choice, the alternatives and why they lost, the consequences, and when it was made. Commits are on `main`; every decision here was made between 9 and 13 October 2026. Where the commits and docs record the alternatives weighed, they are given as recorded; where they don't, the alternatives listed are the obvious ones and why they would lose, not a record of a debate.
Why the Poppy Demo Agent is built the way it is. The [spec](../pda-spec.md) says what is built and how; this file records the choices behind it, as decision records: the context, the choice, the alternatives and why they lost, the consequences, and when it was made. Each decision records when it was made. Where the commits and docs record the alternatives weighed, they are given as recorded; where they don't, the alternatives listed are the obvious ones and why they would lose, not a record of a debate.

Back to the [README](../README.md) · What's left to deploy and check: [deployment-tasks.md](deployment-tasks.md)

Expand Down Expand Up @@ -45,6 +45,9 @@ One Cloudflare Worker serves the page, signs people in with Google or GitHub, se
33. [pi-durable 1.3: reopening pi after a storage error, no caches on timers, pi's storage conformance](#33-pi-durable-13-reopening-pi-after-a-storage-error-no-caches-on-timers-pis-storage-conformance)
34. [read_url hands the page to a reader with no tools](#34-read_url-hands-the-page-to-a-reader-with-no-tools)
35. [Outcomes on the step that asked, and photo uploads decided on one card](#35-outcomes-on-the-step-that-asked-and-photo-uploads-decided-on-one-card)
36. [Draft 0.3 beside 0.2](#36-draft-03-beside-02-a-client_id-per-version-our-card-before-the-companys-terms-and-sessions-that-outlive-sign-out)
37. [0.3 alone](#37-03-alone-what-dropping-01-and-02-overturns-and-settles)
38. [Task requests use the Company's approval boundary](#38-task-requests-use-the-companys-approval-boundary)

## 1. A Worker and one Durable Object per person

Expand Down Expand Up @@ -502,6 +505,8 @@ Each of these closed a specific gap, and each has a test:

## 36. Draft 0.3 beside 0.2: a client_id per version, our card before the Company's terms, and Sessions that outlive sign-out

The preliminary-card policy below was superseded by [decision 38](#38-task-requests-use-the-companys-approval-boundary). The original choice remains recorded here.

- **Context.** Upstream rewrote draft 0.3 on 28 October ([snapshot](../spec/draft-0.3-retrieved-2026-10-28/README.md)): a `Poppy-Session` JWT on every request, signed with a delegated key; plain OAuth for accounts; a browser join through `{browser_session_endpoint}/authorize`; Operations version 2, where a Company refuses a write with the operation and the same request comes back with the approval; Mediated Sign-In as a token-endpoint grant; `author` on messages. Six live Companies already declare 0.3, and Print with Poppy, the one we use most, is on 0.2 with Operations 1. Three choices weren't settled by the text.
- **Decision.**
- **A client_id per protocol version.** A client metadata document lists each extension once, with one major `version` (3.3), and Operations 2 counts only when both sides list `"2"`. Listing `"2"` would end Operations 1 at 0.2 Companies; listing `"1"` would mean 0.3 Companies never return operations to us. So 0.3 Companies get `/poppy/0.3/client.json`, which lists Operations 2, and 0.1 and 0.2 Companies keep `/poppy/client.json`, which lists Operations 1. Both use the same `jwks_uri` and redirect URI (`src/poppy/keys.ts`, `src/poppy/routes.ts`, `PoppyClient.clientIdFor`).
Expand All @@ -528,3 +533,13 @@ Each of these closed a specific gap, and each has a test:
- **Alternatives.** *Keep 0.2 for Print with Poppy.* It is the Company we use most, but it would keep every cost above for one Company, and its maintainers can move to 0.3. *Wait for upstream to commit 0.3.* Six live Companies already declared it, and the snapshot pin with a drift check gives us the same reproducibility.
- **Consequences.** Every Company on 0.1 or 0.2, Print with Poppy among them, is refused until it moves to 0.3, and a deployed agent's accounts there go unused. A Company that allowlisted `/poppy/0.3/client.json` sees `/poppy/client.json`, and the User signs in again. The interop grid has our agent and our mock, with no third party, until a 0.3 peer is pinned. An approval now takes two cards at every Company that asks for one; issue 40 in [poppy-0.3-issues.md](poppy-0.3-issues.md#40-nothing-says-which-writes-need-approval-so-a-careful-agent-asks-the-user-twice) asks upstream for the marker that would make it one.
- **When.** 28 October 2026.

## 38. Task requests use the Company's approval boundary

- **Context.** The owner's 29 October live run showed premature cards and repeated order requests. Our preliminary card asked about an HTTP request before the Company supplied its terms; its intermediate result started another model turn. Operations 2 §§1, 4–6 instead sends the task request first, and the Company chooses which actions need confirmation. The guides discourage confirming routine changes the User already requested.
- **Decision.** Send task-authorized OpenAPI writes and MCP calls normally. Ask only when the Company returns an operation, using its exact summary and revision. Keep separate consent for disclosing the User's photos and for website form submission. Store the request before dispatch; reuse pending terms across fresh model calls and return recorded outcomes on tool replay. A handoff to terms does not wake the model. Successful result URL/link fields reach the User directly as labelled HTTPS links; summaries remain inert text.
- **Alternatives.** Keeping two cards preserves our extra per-write confirmation policy, but that policy caused the premature decision and is not required by Poppy. A new upstream marker is unnecessary for the specified Company-driven flow. Relying on a prompt alone to avoid repeated requests would leave no durable pending-request guard.
- **Consequences.** A Company may perform a routine task request without another click; the agent must keep it within the User's task. This is an explicit change to our policy, not a claim that types can prove a model's intent. This pre-1.0 agent has no old-flow compatibility: stored approvals use version 3 with explicit bindings and withdrawal generations; earlier forms and preliminary API-write cards are refused, not migrated. Current-flow tests retain unknown-outcome holds and withdrawal checks. Lost approved responses still use the conservative unknown-outcome/reconciliation path; automatic same-approval recovery beyond the transport's existing retries is not added here. Issue 40 is withdrawn. Returned links are not proof of payment, and the reported live checkout failure's exact cause remains unestablished.
- **Audit follow-up (30 October).** Every coalesced call gets a durable mapping; unchanged terms on a fresh attempt get a new immutable decision, so delayed clicks cannot claim it. Returned terms retain the actual transport's authority. Only an unapproved task may follow a known `invalid_session` refusal without changing account or withdrawal generation. A changed MCP read-only annotation cannot bypass an already recorded outcome. Recovery republishes committed pending terms without sending or deciding them. Sixteen process-kill probes cover approval and initial-task boundaries, plus real Pi MCP settlement and its unsafe negative control.
- **Diagnostics.** Keep safe per-flow event copies separately from the newest-200 log (50 flows, 200 events/256 KiB each). Export linked lifecycle metadata, not stored requests/results or unrelated protocol logs. Shared unit context and missing pruned history are disclosed. Link-rejection reasons and client-reported source/anchor equality are counts only; no URL value or hash is retained.
- **When.** 29 October 2026, after the owner requested the correction; audited 30 October.
Loading