personal-agent-protocol 0.3.2__tar.gz → 0.4.0__tar.gz

personal_agent_protocol-0.4.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+<!--
+  ~ Copyright (c) 2023-2024 Datalayer, Inc.
+  ~
+  ~ BSD 3-Clause License
+-->
+
+# Changelog
+
+## 0.4.0 (2026-10-11)
+
+Both sides of PAP draft 0.1 and Operations v1, in Python and TypeScript.
+
+- **Personal agent:** Account Tokens (refresh, serialized rotation, narrowing,
+  revocation), Mediated Sign-In with protected input, conversation streaming
+  (SSE, `text-delta`, `Last-Event-ID`), handoff, Direct Conversations and
+  closing, the Operations v1 client (exact approval, standing permissions,
+  recovery), resource-bound MCP Bearer, OpenAPI and MCP clients, operations
+  from every channel.
+- **Company:** a framework-neutral reference company assembled from Reactor
+  points (`pap.company.*`), served over ASGI (Python) and node:http(s)
+  (TypeScript): discovery, Sessions, Direct, Device and Mediated Sign-In,
+  Account Tokens, conversations, an OpenAPI API and an MCP endpoint, the
+  browser session, Operations performed at most once.
+- **Demonstrations:** a user with a company (Manzanita), two companies working
+  together (Ledgerly at Northwind Bank), served in process or over real TCP
+  and TLS (`server` extra).
+- **Conformance:** the requirement ledger of every MUST and SHOULD
+  (`protocol/requirements.yaml`), 113 fixture cases, a runner with JSON and
+  JUnit output (91 of 91 against the reference company over TLS), and the four
+  Python/TypeScript pairings.
+- **CLI:** `pap sessions`, `auth`, `api`, `conversations`, `operations`,
+  `requirements`, `conformance`, with protected input never as an option.

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: personal-agent-protocol
-Version: 0.3.2
+Version: 0.4.0
 Summary: Python SDK for Personal Agent Protocol
 Project-URL: Home, https://github.com/datalayer/personal-agent-protocol
 Project-URL: Documentation, https://personalagentprotocol.org/docs
@@ -46,6 +46,7 @@ Requires-Dist: datalayer-reactor<2,>=1.0.5
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: pyjwt[crypto]<3,>=2.13
+Requires-Dist: pyyaml<7,>=6
 Requires-Dist: typer<1,>=0.12
 Provides-Extra: examples
 Requires-Dist: pydantic-ai-slim[openai]<3,>=2.35.0; extra == 'examples'
@@ -53,10 +54,13 @@ Provides-Extra: lint
 Requires-Dist: mdformat-gfm>=0.3.5; extra == 'lint'
 Requires-Dist: mdformat>0.7; extra == 'lint'
 Requires-Dist: ruff; extra == 'lint'
+Provides-Extra: server
+Requires-Dist: uvicorn>=0.30; extra == 'server'
 Provides-Extra: test
 Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
 Requires-Dist: pytest-cov>=4.1; extra == 'test'
 Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: uvicorn>=0.30; extra == 'test'
 Provides-Extra: typing
 Requires-Dist: mypy>=0.990; extra == 'typing'
 Description-Content-Type: text/markdown
@@ -71,12 +75,12 @@ Description-Content-Type: text/markdown
 
 # 🤖 🌸 Personal Agent Protocol
 
-![Personal Agent Protocol demo](https://images.datalayer.io/products/personal-agent-protocol/pap-demo.gif)
-
 Python and TypeScript SDKs for the
 [Personal Agent Protocol](https://personalagentprotocol.org), currently
 targeting [draft 0.1](https://personalagentprotocol.org/docs/spec).
 
+![Personal Agent Protocol demo](https://images.datalayer.io/products/personal-agent-protocol/pap-demo.gif)
+
 PAP lets a personal agent discover and talk to a company's agent on behalf of
 a person. The company remains responsible for its identity, authorization,
 data, and actions; the personal agent does not need the person's company

personal_agent_protocol-0.4.0/docs/docs/examples/account-tokens.mdx

@@ -0,0 +1,73 @@
+---
+title: Account Tokens
+description: Keep a user signed in with a rotating Account Token that never leaves the host.
+---
+
+# Account Tokens
+
+A sign-in returns an Account Token (the OAuth `refresh_token`). The personal
+agent uses it only at the company's token and revocation endpoints, to sign a
+Session in again after its short-lived Session Token expires. The paired
+examples run the real `AccountTokenClient` against Manzanita Outfitters, the
+reference company in `personal_agent_protocol.demo`, with real keys over HTTP
+in one process.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Tool as Agent tool
+  participant SDK as AccountTokenClient
+  participant Lock as pap.accountTokenLock
+  participant Vault as pap.tokenStore
+  participant Company as Company token endpoint
+  Tool->>SDK: refresh(reference, session_id)
+  SDK->>Lock: Hold the reference
+  SDK->>Vault: Read Account Token
+  SDK->>Company: refresh_token grant + session_id + assertion + DPoP
+  Company-->>SDK: Signed-in Session Token + rotated Account Token
+  SDK->>Vault: Replace the old token before releasing the lock
+  SDK-->>Tool: signed_in, rotated, granted scopes
+  Tool->>SDK: refresh(reference, scopes=orders:read)
+  SDK->>Company: Narrower scope
+  Company-->>SDK: Session with orders:read
+  Tool->>SDK: refresh(reference, scopes=orders:admin)
+  Company-->>SDK: invalid_scope
+  SDK-->>Tool: re_consent_required (sign the user in again)
+  Note over Company: Ninety-one days later
+  SDK->>Company: refresh_token grant
+  Company-->>SDK: invalid_grant
+  SDK->>Vault: Delete the stored copy
+  SDK-->>Tool: signed_out
+  Tool->>SDK: revoke(reference)
+  SDK->>Company: RFC 7009 revocation
+  Company-->>SDK: 200, every Session signed in with it is signed out
+  SDK->>Vault: Delete once the company answered
+```
+
+The walkthrough:
+
+1. **Refresh** signs the same Session in again (`session_id` unchanged) and the
+   company rotates the token. The new one replaces the old in the token store
+   before the call returns.
+2. **Two refreshes at once** both succeed: the Reactor `pap.accountTokenLock`
+   serializes them, so the second presents the token the first rotated in, not
+   the one the company already revoked.
+3. **Narrower** scopes are granted; **wider** scopes come back as
+   `re_consent_required`, a decision for the user, never a retry.
+4. An **expired** token draws `invalid_grant`; the SDK deletes it and the
+   Session continues signed out.
+5. **Revocation** signs out every Session signed in with the token. The next
+   question to the company draws an `authorization` event again.
+
+The model sees statuses (`signed_in`, `re_consent_required`, `signed_out`),
+whether a rotation happened, and scope names. The Account Token, Session
+Tokens, client assertions, and DPoP proofs stay host-only, behind opaque
+references in Reactor stores.
+
+TypeScript has the same client: `new AccountTokenClient({ reactor, fetch })`,
+with `refresh(reference, { context, sessionId, scopes })` and `revoke()`, and
+the lock contributed at `AccountTokenLocks`.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/account-tokens).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/account-tokens).
+- Read the [Account Tokens guide](/guides/account-tokens/).

personal_agent_protocol-0.4.0/docs/docs/examples/conversation-control.mdx

@@ -0,0 +1,63 @@
+---
+title: Conversation control
+description: Sign in mid-conversation, open a Direct Conversation, hand off to a person, and close.
+---
+
+# Conversation control
+
+A conversation is more than messages. The company can ask the user to sign in
+part-way through, the user can talk to the company directly through the
+agent's interface, either side can bring in a person, and the agent can close
+it. The paired examples drive one Manzanita conversation through all four,
+against a Manzanita with a support desk staffed.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Ada
+  participant Atlas as Atlas (personal agent)
+  participant Company as Manzanita
+  Atlas->>Company: Where is my jacket order? (signed out)
+  Company-->>Atlas: authorization: sign_in_required (orders:read orders:write)
+  Atlas->>Ada: Sign in on Manzanita's page
+  Ada->>Company: Approves the device code
+  Atlas->>Company: Same conversation, signed-in token
+  Company-->>Atlas: Your order ord_7Hk2 … delivered
+  Ada->>Atlas: I'd like to ask about sizing myself
+  Atlas->>Company: start_direct(parent) with sender human
+  Company-->>Atlas: Direct Conversation cnv_d
+  Atlas->>Company: Message or handoff on the parent
+  Company-->>Atlas: 409 direct_conversation_open (conversation_id cnv_d)
+  Atlas->>Company: close(cnv_d)
+  Company-->>Atlas: Parent: direct_closed
+  Atlas->>Company: handoff(parent)
+  Company-->>Atlas: state queued, then idle with responder human
+  Atlas->>Company: close(parent)
+  Company-->>Atlas: closed, later messages are conversation_closed
+```
+
+- **Sign-in mid-conversation (§7.11).** An `authorization` event says what is
+  missing (`sign_in_required` or `insufficient_scope`) and which scopes. The
+  host signs in with any mode the company offers and keeps sending to the
+  **same conversation ID** with the new token.
+- **Direct Conversations (§7.10).** Only the personal agent starts one, for
+  the user to talk with the company in the agent's interface. While it is
+  open, the parent refuses messages and handoff with
+  `direct_conversation_open`; the SDK puts the open conversation's ID in
+  `error.details["conversation_id"]`.
+- **Handoff (§7.9).** `handoff()` asks for a person; the conversation is
+  `queued` until one takes it, then `responder` is `human`. When no one is
+  available the company says so and the agent continues.
+- **Closing (§7.12).** `close()` ends the conversation; operations it
+  proposed or started are not cancelled.
+
+The model sees event types, statuses, the company's answers, and error codes.
+Tokens, the device code, and proofs stay host-only; the user code is shown to
+the user by the host, not by the model.
+
+TypeScript: `startDirect()`, `handoff()`, and `close()` on
+`ConversationClient`, with the same error codes and details.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/conversation-control).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/conversation-control).
+- Read the [conversations guide](/guides/conversations/).

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.4.0}/docs/docs/examples/conversation-events.mdx

@@ -50,8 +50,8 @@ missing.
 
 Session Tokens, DPoP proofs, pairwise identity, and the saved cursor remain in
 the trusted host. A model or UI receives only the event fields it needs. A
-future SSE slice will add reconnect and `text-delta` handling; applications
-must not treat a `text-delta` as an actionable final message.
+company that streams can be read over SSE instead, with reconnects and
+display-only `text-delta` frames: see [conversation streaming](./conversation-streaming).
 
 Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/conversation-events)
 or the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/conversation-events).

personal_agent_protocol-0.4.0/docs/docs/examples/conversation-streaming.mdx

@@ -0,0 +1,65 @@
+---
+title: Conversation streaming
+description: Stream a company's reply over SSE, reconnect from Last-Event-ID, and never act on a delta.
+---
+
+# Conversation streaming
+
+A company that streams answers `GET …/events` with `Accept: text/event-stream`.
+Events arrive as SSE frames with their IDs, and `text-delta` frames carry a
+message while it is still being written. The paired examples stream a
+Manzanita conversation through a connection that breaks in the middle of the
+company's first reply.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Tool as Agent tool
+  participant SDK as ConversationClient.stream()
+  participant Net as Network
+  participant Company
+  SDK->>Company: GET /events (Accept: text/event-stream) + DPoP
+  Company-->>SDK: id evt_1 (user message)
+  Company-->>SDK: text-delta msg_r (half of the reply)
+  Net--xSDK: Connection drops before message msg_r
+  SDK-->>Tool: TextDelta (actionable = false)
+  SDK-->>Tool: StreamReconnected(last_event_id=evt_1, discarded=[msg_r])
+  SDK->>Company: GET /events, Last-Event-ID: evt_1
+  Company-->>SDK: text-delta msg_r, id evt_2 (complete message)
+  SDK-->>Tool: Message event evt_2 (the one to show and act on)
+  Company-->>SDK: Stream ends, conversation still open
+  SDK-->>Tool: StreamReconnected(last_event_id=evt_2)
+  Tool->>Company: close()
+  SDK->>Company: GET /events, Last-Event-ID: evt_2
+  Company-->>SDK: id evt_3 state closed
+  SDK-->>Tool: State closed, the iterator ends
+```
+
+What the stream guarantees:
+
+- **Deltas are display only.** `TextDelta.actionable` is always `False`; the
+  complete `message` event replaces the pieces. A host routes deltas to a
+  typing indicator, never to anything that acts.
+- **Reconnects resume.** When the company ends the stream, the SDK reopens it
+  with `Last-Event-ID` set to the last event handled, and yields
+  `StreamReconnected` so the UI knows.
+- **Partial messages are discarded.** Pieces whose complete message never
+  arrived are listed in `discarded_message_ids`, so the display drops them.
+- **No event twice.** Replayed events are suppressed by ID, within a bounded
+  set that fails closed.
+- **Bounded retries.** After `max_reconnects` reconnects in a row without a
+  new event, the stream fails with `stream_unavailable`. A company that does
+  not stream answers JSON; the SDK raises `sse_unsupported` and the host falls
+  back to the long-polling `events()` reader.
+
+The model sees the company's complete messages, how many deltas and
+reconnects there were, and that nothing was delivered twice. The Session
+Token, DPoP proofs, and pairwise identity stay host-only.
+
+TypeScript: `for await (const item of client.stream(endpoint, id, options))`,
+where `item.kind` is `"text-delta"` or `"reconnected"` for the two
+stream-only items.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/conversation-streaming).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/conversation-streaming).
+- Read the [conversations guide](/guides/conversations/).

personal_agent_protocol-0.4.0/docs/docs/examples/device-sign-in.mdx

@@ -0,0 +1,44 @@
+---
+title: Device Sign-In
+description: Hand authentication to the user, pace polling, and protect every credential.
+---
+
+# Device Sign-In
+
+The paired examples use the real SDK state machine against a deterministic
+company transport. They demonstrate a terminal-style personal agent that
+cannot receive a browser callback.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User
+  participant Tool as Read-only agent tool
+  participant SDK as DeviceSignInClient
+  participant Company
+  participant Vault as Reactor stores
+  Tool->>SDK: Begin for existing signed-out Session
+  SDK->>Company: Request device authorization
+  Company-->>SDK: Link, user code, interval, private device code
+  SDK->>Vault: Save private device code
+  SDK-->>Tool: Link, user code, opaque reference
+  Tool-->>User: Authenticate on company page
+  SDK->>Company: Poll at interval with DPoP
+  Company-->>SDK: authorization_pending
+  SDK->>Company: Poll at interval
+  Company-->>SDK: slow_down
+  Note over SDK: Increase interval by five seconds
+  SDK->>Company: Poll at new interval
+  Company-->>SDK: Signed-in Session + Account Token + partial scopes
+  SDK->>Vault: Store Account Token
+  SDK-->>Tool: Safe lifecycle evidence + opaque token reference
+```
+
+The model sees that the link and code were presented, early polling was
+suppressed, pending and slow-down responses were respected, the original
+Session was upgraded, and one requested scope was omitted. It never sees the
+device code, assertions, proofs, or tokens.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/device-sign-in).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/device-sign-in).
+- Read the production [Device Sign-In guide](/guides/device-sign-in/).

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.4.0}/docs/docs/examples/index.mdx

@@ -22,9 +22,19 @@ capability owns sensitive work, and what may safely cross into model context.
 | [Session lifecycle](./session-lifecycle)               | Start, retry, and renew a signed-out Session                  | An authorization server    |
 | [Direct Sign-In lifecycle](./direct-sign-in-lifecycle) | Upgrade the same Session after user consent                   | A browser callback         |
 | [Browser Session](./browser-session)                   | Join a controlled browser to the same Session                 | A signed browser assertion |
+| [Account Tokens](./account-tokens) | Refresh, rotate, narrow, expire, and revoke without exposing the token | A signed-in Session |
+| [Mediated Sign-In](./mediated-sign-in) | Relay protected input to one endpoint, then a one-time code | Declared mediated fields |
+| [Conversation streaming](./conversation-streaming) | Stream over SSE, reconnect from `Last-Event-ID`, never act on deltas | An open conversation |
+| [Conversation control](./conversation-control) | Sign in mid-conversation, go direct, hand off, and close | An `authorization` event |
+| [Operations](./operations) | Confirm the exact revision, recover lost answers, use standing permissions | A proposed operation |
+| [A user with a company](./user-with-a-company) | The whole journey with Manzanita, both sides from the SDK | A user's request |
+| [Two companies](./two-companies) | Ledgerly acts for Ada at Northwind, by composition | Two PAP relationships |
 
 The examples use deterministic or local transports where needed, so they can
-teach the boundary without real credentials. Production hosts replace those
+teach the boundary without real credentials. The newer flows run against the
+reference company in `personal_agent_protocol.demo`: real keys and real HTTP
+over ASGI in one process, with no network. The two journeys at the end of the
+table combine several features; each other page showcases one. Production hosts replace those
 fixtures through Reactor contributions for egress, state, browsers, signing,
 DPoP, key custody, and token storage.
 

personal_agent_protocol-0.4.0/docs/docs/examples/mediated-sign-in.mdx

@@ -0,0 +1,60 @@
+---
+title: Mediated Sign-In
+description: Relay the user's credentials to one company endpoint, once, without a model seeing them.
+---
+
+# Mediated Sign-In
+
+Some companies cannot send their users to a browser. They declare the fields
+they need (`auth.mediated.fields`) and an endpoint on their own domain, and
+the personal agent relays what the user types. It is the one sign-in mode
+where a password passes through the agent's host, so the SDK narrows what the
+host can do with it. The paired examples run the real `MediatedSignInClient`
+against Manzanita Outfitters, which asks for an email, a password, and then a
+one-time code.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User
+  participant Tool as Agent tool
+  participant SDK as MediatedSignInClient
+  participant Input as pap.protectedInput (host surface)
+  participant Company as Company mediated endpoint
+  Tool->>SDK: sign_in(declared fields, signed-out Session)
+  SDK->>SDK: Endpoint on the company's domain? Otherwise refuse before asking
+  SDK->>Input: Ask for Email and Password for manzanita.example
+  User->>Input: Types them (never into the chat)
+  SDK->>Company: POST credentials once + DPoP, no redirect followed
+  SDK->>SDK: Drop the values
+  Company-->>SDK: code_required, sign_in_id, sent_to a•••@example.com
+  SDK-->>Tool: code_required + opaque reference + masked sent_to
+  Tool->>SDK: submit_code(reference, same Session)
+  SDK->>Input: Ask for the code
+  User->>Input: Types the code
+  SDK->>Company: POST code only to …/sign_in_id
+  Company-->>SDK: complete + signed-in Session + Account Token
+  SDK-->>Tool: complete, granted scopes, Account Token reference
+```
+
+The walkthrough also shows the refusals:
+
+- An endpoint off the company's domain is `unsafe_mediated_endpoint`, raised
+  before the user is asked anything.
+- The protected input must answer exactly the declared fields, none empty.
+- Only the Session that started a sign-in can finish it
+  (`session_mismatch`); the pending state is kept for the right one.
+- A wrong code is `code_required` again with the same reference; the company
+  ends the sign-in with `failed` after its attempt limit.
+
+The model sees field labels, which fields are secret, the company's domain,
+the masked destination of the code, statuses, and granted scopes. The
+credentials and the code exist only in the host's protected input and in the
+one request body; the Session Token and Account Token stay in Reactor stores.
+
+TypeScript: `new MediatedSignInClient({ reactor, fetch })` with `signIn()` and
+`submitCode()`, the trusted surface contributed at `ProtectedInputs`.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/mediated-sign-in).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/mediated-sign-in).
+- Read the [Mediated Sign-In guide](/guides/mediated-sign-in/).

personal_agent_protocol-0.4.0/docs/docs/examples/operations.mdx

@@ -0,0 +1,76 @@
+---
+title: Operations
+description: Confirm exactly what the user approved, at most once, and recover a lost answer.
+---
+
+# Operations
+
+An operation is something a company proposes and performs only once it is
+confirmed: a payment, an exchange, a cancellation. The Operations extension
+(version 1) makes the approval exact and durable. The paired examples confirm
+Northwind Bank's proposed payments; Northwind marks payments as not requiring
+the user's own approval, so a standing permission may confirm them too.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Ada
+  participant Atlas as Atlas host
+  participant Store as pap.standingPermissionStore
+  participant Bank as Northwind operations endpoint
+  Note over Atlas,Bank: Both poppy.json and agent.json list operations version 1
+  Bank-->>Atlas: Proposal op_1 revision 1 (EUR 1250.00 to Acme GmbH)
+  Atlas->>Store: reserve(company, account, action, terms)
+  Store-->>Atlas: Nothing covers it
+  Atlas->>Ada: Show the summary and terms
+  Ada->>Atlas: Approve revision 1 (approve: revision + digest)
+  Note over Bank: The bank revises: EUR 1262.50, a fee added
+  Atlas->>Bank: POST op_1/confirm (revision 1, approved_by user)
+  Bank-->>Atlas: 409 terms_changed + revision 2
+  Atlas->>Ada: What changed: summary, amount.amount
+  Ada->>Atlas: Approve revision 2
+  Atlas->>Bank: POST op_1/confirm (revision 2)
+  Bank--xAtlas: Performed, but the answer is lost
+  Atlas->>Bank: GET op_1 (same ID, never re-proposed)
+  Bank-->>Atlas: succeeded + result.summary
+  Bank-->>Atlas: Proposal op_2 (EUR 980.00)
+  Atlas->>Store: reserve: payee, amount ≤ 2000.00, EUR, one use
+  Store-->>Atlas: Reservation
+  Atlas->>Bank: POST op_2/confirm (approved_by standing_permission)
+  Bank-->>Atlas: succeeded
+  Atlas->>Store: commit (a refusal would release the use)
+```
+
+The walkthrough:
+
+1. **Negotiation.** `operations_endpoint()` returns the endpoint only when the
+   company and the agent both list `operations` version 1. A company answers
+   an agent that does not with `extension_required`.
+2. **Exact approval.** `approve(operation)` records the revision and a digest
+   of its summary and terms. A confirmation for any other revision is refused
+   locally (`approval_mismatch`); a chat message never confirms anything.
+3. **Changed terms.** `terms_changed` returns the new revision and the changed
+   term paths, to show the user before asking again.
+4. **Recovery.** If a confirm's answer is lost, the SDK reads the same
+   operation back. It is never re-proposed or assumed failed; a retried
+   confirm returns the same record, and the company performs it once.
+5. **Standing permissions.** A permission names one company, account, and
+   action, with limits on term paths (a maximum or allowed values), an expiry,
+   and optional uses. The Reactor `pap.standingPermissionStore` reserves a use
+   only when every limit covers the revision; the use is committed when the
+   company confirms and released when it refuses. A revision that requires the
+   user's approval is never confirmed this way.
+6. **Cancel.** A proposal becomes `cancelled`, and the company's
+   `result.summary` says nothing was changed.
+
+The model sees states, revisions, changed term paths, error codes, and the
+company's `result.summary` as written. Tokens and proofs stay host-only, and
+the decision to approve stays with the user in the host's own interface.
+
+TypeScript: `OperationsClient`, `operationsEndpoint()`, and `approve()`
+(asynchronous there, since the digest uses Web Crypto), with standing
+permissions contributed at `StandingPermissionStores`.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/operations).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/operations).
+- Read the [Operations guide](/guides/operations/).

personal_agent_protocol-0.4.0/docs/docs/examples/two-companies.mdx

@@ -0,0 +1,73 @@
+---
+title: Two companies
+description: Ledgerly pays Ada's invoices at Northwind Bank, by composing two PAP relationships.
+---
+
+# Two companies
+
+:::caution Composition, not a draft 0.1 feature
+
+PAP draft 0.1 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.
+
+:::
+
+Ledgerly, an accounting firm, pays Ada's supplier invoices from her Northwind
+account. Every approval is an Operation, never a chat message, and a standing
+permission is itself an Operation Ada approves.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Ada
+  participant Atlas as Atlas (Ada's agent)
+  participant L as Ledgerly (company to Atlas, agent at Northwind)
+  participant N as Northwind Bank
+  Atlas->>L: Pay INV-0042 (signed in to Ledgerly)
+  L-->>Atlas: Connect Ledgerly: open northwind.example/device
+  Ada->>N: Approves Ledgerly's code on Northwind's page
+  Atlas->>L: Done. Pay INV-0042
+  L->>N: Conversation: pay INV-0042
+  N-->>L: Operation n_1: EUR 1250.00 to Acme GmbH
+  L-->>Atlas: Operation l_1 quoting n_1 as written
+  Ada->>Atlas: Approve l_1
+  Atlas->>L: Confirm l_1 (approved_by user)
+  L->>N: n_1 unchanged? Confirm n_1 (approved_by user)
+  N-->>L: Sent … Bank reference NW-0001
+  L-->>Atlas: Northwind Bank: Sent … NW-0001
+  Atlas->>L: Allow Acme payments up to EUR 2000 without asking
+  L-->>Atlas: Operation: standing permission, 5 uses, 30 days
+  Ada->>Atlas: Approve it
+  Atlas->>L: Pay INV-0043
+  L->>N: Pay, n_2 EUR 980.00 within bounds
+  L->>N: Confirm n_2 (approved_by standing_permission)
+  L-->>Atlas: Paid under your standing permission: …
+  Atlas->>L: Pay INV-0044
+  L->>N: n_3 EUR 3400.00 beyond bounds
+  L-->>Atlas: Operation for Ada to approve
+```
+
+What each party enforces:
+
+- **Northwind** sees a personal agent called Ledgerly, signed in by Ada on
+  Northwind's own page, confirming its proposals. Its records say who approved
+  each payment: `user` for the first, `standing_permission` for the second.
+- **Ledgerly** confirms at Northwind only the exact revision Ada approved: its
+  executor checks Northwind's revision and terms are unchanged before
+  confirming, and relays Northwind's `result.summary` as written. Within the
+  standing permission's term-by-term bounds it confirms itself and tells Ada
+  what was done; beyond them, it proposes a new operation for her.
+- **Atlas** treats Ledgerly like any company: it shows each operation's
+  summary and terms, and confirms only what Ada approved.
+
+The model sees summaries as the companies wrote them, who approved each
+payment, and that the composition involves no company-to-company protocol.
+It never sees a token, code, or proof of any of the three parties.
+
+The same world runs in `personal_agent_protocol/__tests__/test_two_companies.py`.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/two-companies).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/two-companies).
+- Read the [Operations guide](/guides/operations/) and the [company guide](/guides/company/).

personal_agent_protocol-0.4.0/docs/docs/examples/user-with-a-company.mdx

@@ -0,0 +1,62 @@
+---
+title: A user with a company
+description: One user, one company, from a first question to a confirmed exchange and sign-out.
+---
+
+# A user with a company
+
+The whole journey of the upstream home page's example: Ada's jacket is not
+warm enough, and she asks her personal agent, Atlas, to exchange it at
+Manzanita Outfitters. Both sides come from this SDK. Manzanita is the
+[reference company](/guides/company/) assembled from Reactor contributions,
+Atlas is a personal agent with a real ES256 identity, and they talk real HTTP
+over ASGI in one process, with no network and no model in the protocol path.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Ada
+  participant Atlas as Atlas (personal agent)
+  participant M as Manzanita (company)
+  Atlas->>M: Discovery + OAuth metadata
+  Atlas->>M: Signed-out Session (assertion + DPoP)
+  Ada->>Atlas: Where is my jacket order?
+  Atlas->>M: Start conversation
+  M-->>Atlas: Sign in first + authorization: sign_in_required
+  Atlas->>M: Device authorization for the same Session
+  Atlas->>Ada: Open manzanita.example/device and enter the code
+  Ada->>M: Signs in and approves on Manzanita's page
+  Atlas->>M: Poll → signed-in Session + Account Token
+  Ada->>Atlas: Exchange it for something warmer
+  Atlas->>M: Same conversation, signed in
+  M-->>Atlas: Operation op_1 rev 1: USD 70.00 more
+  Atlas->>Ada: Show summary and terms
+  Ada->>Atlas: Approve this revision
+  Atlas->>M: Confirm rev 1 (approved_by user)
+  M-->>Atlas: succeeded + result.summary
+  Atlas->>M: Confirm again (a retry)
+  M-->>Atlas: Same record, performed once
+  Atlas->>M: Refresh narrowed to orders:read
+  Ada->>Atlas: Sign me out
+  Atlas->>M: Revoke the Account Token
+```
+
+Each step is one feature, documented on its own page:
+[company discovery](./company-discovery), [session lifecycle](./session-lifecycle),
+[conversation control](./conversation-control) for the `authorization`
+event, [Device Sign-In](./device-sign-in), [Operations](./operations), and
+[Account Tokens](./account-tokens).
+
+The model sees the steps in plain words: what the company asked, where Ada
+signed in, what was proposed, what she approved, and what Manzanita did, in
+its own words. It never sees the device code, a token, an assertion, or a
+proof. Ada approves in the host's interface; the model can explain the
+proposal but cannot approve it.
+
+The same world runs in `personal_agent_protocol/__tests__/test_company_end_to_end.py`,
+which also covers Mediated Sign-In with a one-time code, streaming, and a
+stranger refused with `conversation_not_found`.
+
+- Run the [Pydantic AI example](https://github.com/datalayer/personal-agent-protocol/tree/main/examples/pydantic-ai/user-with-a-company).
+- Run the [Agent Runtimes example](https://github.com/datalayer/agent-runtimes/tree/main/examples/personal-agent-protocol/user-with-a-company).
+- Read the [company guide](/guides/company/).