Skip to main content

SDK design

The Python and TypeScript packages share one protocol ledger, fixtures, public concepts, and Reactor contribution IDs while retaining idiomatic language APIs.

Repository structure​

personal-agent-protocol/
├── protocol/                  # upstream revision, requirements, shared fixtures
├── personal_agent_protocol/  # Python package
├── src/                       # TypeScript package source (package.json is at root)
├── src/__tests__/                  # TypeScript tests
├── personal_agent_protocol/__tests__/ # Python tests
├── examples/                  # language and interoperability examples
├── conformance/               # planned black-box suites
└── docs/                      # this Docusaurus site

The protocol directory is an implementation aid, not a fork of the standard. Wire models retain unknown fields for compatible minor versions. Handwritten validation owns cross-field, URL-trust, token, and state-transition rules.

Shared public concepts​

Both SDKs converge on discovery and OAuth metadata, personal-agent metadata, sessions and token references, sign-in state machines, conversations and event streams, operations and revisions, and safe typed errors. Secrets redact themselves in representations and serialized diagnostic output. Applications receive handles or references; only the credential store and final HTTP layer receive raw secrets.

Reactor contribution contract​

Every point, its contract, default, and tenant scope is in protocol/reactor-points.json, which both SDKs' tests check (see Contribution points).

Lower contribution order wins. Equal winning priorities fail closed. Plugins cannot disable issuer/domain binding, redaction, proof freshness, token/resource binding, replay protection, or exact-revision approval.

Python and TypeScript export the same point IDs and contracts. The core plugin provides the clock, random source, metadata transport and URL policy, cache, Account Token lock, retry policy, and rate-limit budget. Signing, DPoP proofs, tokens, sign-in state, pairwise IDs, browser handoff, and protected input intentionally have no fallback: a caller that needs one and has no active provider fails closed. Tests cover, for every point, its default, a host contribution, its replacement by a lower order, its removal with its plugin, and equal-priority ambiguity, plus the tenant-scoped points.

Compatibility policy​

  • SDKs remain 0.x while PAP is a draft and state the supported profile.
  • Unsupported major versions are rejected; later minor versions and unknown fields are tolerated as the protocol requires.
  • Deprecated draft behavior requires an explicit compatibility profile.
  • Python and TypeScript run over the same fixtures before either releases.
  • Upstream changes are reviewed; scraped documentation never changes wire behavior automatically.

See Architecture, Conformance, and Protocol status for current evidence.