@poppykit/client 0.0.0-stage → 0.1.0

package/API.md

@@ -0,0 +1,25 @@
+# API reference
+
+Every export has an accompanying `dist/*.d.ts` declaration; use editor completion
+for complete option/result types. This map describes the supported integration seams.
+
+| Entry point | Main exports | Guide |
+| --- | --- | --- |
+| `@poppykit/client` | `createMetadataResolver`, `createNodeTransport` | [README](README.md), [delivery](DELIVERY.md) |
+| `@poppykit/client` | `createClientAuth`, `AuthFailure`, authentication/identity/input types | [authentication](AUTH.md) |
+| `@poppykit/client` | `createConversationClient`, `ConversationError`, `parseEventStream` | [delivery](DELIVERY.md) |
+| `@poppykit/client` | `ApiTarget`, `AgentBrowserController`, `FeedbackReport` types | [integrations](INTEGRATIONS.md) |
+| `@poppykit/client/sqlite` | `SqliteAuthStore`, `SqliteConversationStore` | [storage](STORAGE.md) |
+| `@poppykit/client/memory` | `MemoryConversationStore` (non-durable) | [storage](STORAGE.md) |
+| `@poppykit/client/provider` | `createProvider`, `createProviderClient`, `createResultCipher` | [provider](PROVIDER.md) |
+| `@poppykit/client/provider/sqlite` | `SqliteProviderStore` | [provider](PROVIDER.md) |
+
+ClientAuth methods include `start/get/list/target`, `authorization`,
+`beginSignIn/continueSignIn/completeSignIn/cancelSignIn/operation`, `renew`,
+`signOut/retryCleanup/recover`, `authorizedFetch`, `apiTarget/apiFetch`,
+`joinBrowser` and `feedback`. Conversation operations bind one connection, issuer
+and endpoint; never substitute profile names or model-provided URLs for that binding.
+
+The [quickstart](examples/quickstart.mjs) is executed by CI. Integration examples
+describe adapters your application supplies; they are not built-in browser drivers
+or general API executors.

package/AUTH.md

@@ -0,0 +1,51 @@
+# Authentication lifecycle
+
+`createClientAuth` owns Direct, Device and Mediated sign-in, token renewal,
+replacement, revocation and abandoned-operation recovery. Call `recover()` on
+startup. Another live process is never interrupted; an ambiguous dispatched
+exchange is uncertain and must not be replayed.
+
+Ask `authorization(connectionId, scopes)` for the current grant, missing scopes
+and advertised methods. Choose a method explicitly in `beginSignIn`. Direct
+requires an HTTPS registered callback and an authenticated browser binding.
+Display its URL in the user's browser. Device returns a checked link/code and
+company identity; call `continueSignIn(operationId)` when its deadline is due.
+Do not automate user approval. Mediated calls the configured `TrustedInput`
+adapter for declared fields and correlated one-time codes. Only trusted UI code
+implements this adapter. Values are cleared after each submission and never
+persisted by the SDK or exposed in public results. Input adapters must not log
+values, keep copies, or return them through model tools.
+
+First-time partial grants complete with `grantedScopes` and `missingScopes`.
+Replacement preserves every old grant scope by default. An explicit
+`requiredExistingScopes` subset permits dropping other old scopes. A rejected
+replacement retains the previous grant and queues the new token for revocation;
+accepted replacements queue the previous token instead. Grants are never unioned.
+`force: true` represents an explicit user request to sign in again. Otherwise a
+sufficient current grant is reused. Run `retryCleanup` to retry durable retirement.
+
+Metadata is refreshed through the supplied resolver. A changed exact issuer or
+saved destination fails with `metadata_changed`; start a new connection after
+reviewing the new metadata. Saved work is never rerouted. Server Retry-After
+deadlines are persisted as absolute decimal milliseconds, including enormous
+values, and survive restarts without a local delay cap.
+
+`start(domain, { anonymous: true })` uses a fresh identity and DPoP key. Ending
+it deletes that private key and local identity; sign-in starts a new regular
+connection/session. Consume the returned connection ID and do not transfer old
+conversations. Regular issuer identity remains stable and separate.
+
+Provider adapters implement J1's `AssertionProvider` and `ProviderIdentity`;
+their authenticated identity supplies the issuer-specific UserID. Only purpose,
+issuer and operation binding are passed for assertions, never arbitrary bytes
+or claims. The operator must publish the signing key. For anonymous sessions a
+separate local `IdentitySigner` is required and its key must also be published in
+the client's JWKS. A provider-only configuration reports `anonymous_unavailable`;
+it never substitutes the provider's stable identity for an anonymous one.
+
+Account Tokens, device codes, PKCE and DPoP keys belong in the configured
+SecretStore; Session Tokens stay in memory. SQLite and secret storage are separate
+commit boundaries. A host must sweep orphan staged secrets only after checking
+ownership and a grace period; crashes between stage and durable reference can
+leave such orphans. Cancellation/revocation generation checks defeat late results.
+Revocation stops future protected work and never automatically reconnects.

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 — initial development release candidate (unpublished)
+
+Discovery, safe HTTPS, all three sign-in methods, partial grants/replacement,
+owner-aware recovery, JSON/SSE conversations, API/browser/feedback hooks, targeted
+SQLite adapters and optional constrained hosted-identity provider.
+
+- Select MIT licensing and ship the complete LICENSE.
+- Prepare public package metadata and the initial 0.1.0 version.
+- Preserve J8 strict TypeScript tests, real subprocess/security regressions and
+  immutable installed-package verification on Linux, macOS and Windows.
+
+No npm publication has occurred. Version 0.x APIs/storage may still change; record
+compatibility and migration/reset implications with future changes. This release
+does not promise stable 1.0 compatibility or certify external host integrations.
+
+## 0.0.0 — historical private development candidates
+
+J1–J8 established protocol capabilities, targeted storage, durable recovery,
+documentation, strict tests and fail-closed release verification. Their prior
+commits/artifact results remain historical evidence for those exact candidates.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+This package targets Personal Agent Protocol draft 0.2. Check the current
+[specification](https://personalagentprotocol.org/docs/0.2/spec) and
+[guides](https://personalagentprotocol.org/docs/0.2/guides); retained snapshots and
+tests are supporting evidence. Distinguish MUST requirements, SHOULD recommendations
+and product choices. Individual extensions and demo/business workflows are excluded.
+
+Use Node 24.12.0, TypeScript 5.9.3 and @types/node 24.10.0.
+Install with the pinned pnpm version in package.json and `pnpm install --frozen-lockfile`.
+Run `npm run typecheck`, `npm run build`, `npm test` and `npm run check:docs`.
+CI partitions tests without omitting any test file; full `npm test` remains useful
+locally. Read [RELEASING.md](RELEASING.md) before changing workflow/release behavior.
+
+Keep changes small and complete: include callers, declarations, regression checks
+and documentation. Do not log credentials, weaken destination validation or silently
+reset persisted data. Pull requests must explain checks actually run and limitations.
+Use the repository's Issues for non-sensitive defects and feature discussions.
+Code is licensed under [MIT](LICENSE). No separate contribution agreement is
+configured; confirm permission for third-party contributions and obtain owner
+authorization before publishing.
+
+## TypeScript test harness and coverage
+
+First-party tests, executable fixtures, process workers and packaged verification
+scripts are canonical `.mts` files. Run `npm run typecheck:tests` for the complete
+strict program and `npm run build:tests` before individual
+`node scripts/run-checks.mjs GROUP` commands (unit, contracts, integration or
+validation). `npm test` performs that checked harness build and runs all groups.
+Build production first with `npm run build`; tests import compiled `dist/*.js`,
+not TypeScript source. No loader or native type stripping replaces the compiler.
+
+The existing TypeScript compiler emits ignored adjacent `.mjs` files only after
+all strict diagnostics pass. Failed builds remove stale canonical outputs.
+`scripts/build-tests.mjs` is compiler/bootstrap tooling, not an unchecked test
+runner. Canonical test sources use LF, enforced by `.gitattributes`, so Linux and
+Windows validate the same exact source bytes. Test output stays outside the npm
+package allowlist. Retained JavaScript release/build tools and packaged examples
+are genuine production tooling/examples; retained protocol captures are references.
+
+Run `npm run coverage` for a production build, checked harness and native Node
+24.12.0 line/branch/function report. `coverage/summary.txt`, `coverage/lcov.info`,
+`coverage/report.json` and `coverage/raw/` are generated local reports. Metrics
+refer to first-party compiled `dist` JavaScript; production emits no source maps
+and no TypeScript remapping is claimed. Third-party `node_modules` is excluded;
+unloaded modules are listed explicitly. Raw child-process reports are retained,
+but arbitrary subprocess execution is not guaranteed to be merged into the native
+runner summary, and killed/crashed workers may not flush counters. Actual installed
+package/OS checks remain separate evidence. No percentage threshold substitutes
+for protocol, negative/security, process and platform assertions.

package/DELIVERY.md

@@ -0,0 +1,113 @@
+# Conversation delivery and transport
+
+The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
+unknown events and partial text remain untrusted data for the host application.
+
+## Client
+
+Bind `createConversationClient` to the existing auth lifecycle:
+
+```ts
+const target = await auth.target(connectionId);
+const conversations = createConversationClient({
+  ...target, connectionId, store, clock: { now: Date.now },
+  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
+  authorization: (id, scopes) => auth.authorization(id, scopes),
+});
+for await (const item of conversations.watch(conversationId, { consumer: 'ui', signal })) {
+  await processEvent(item.event);
+  await item.ack();
+}
+```
+
+`authorization(eventOrError)` returns the single auth lifecycle's verified
+required/granted/missing scopes and eligible methods. The UI requests consent and
+chooses an advertised method; Device or Mediated does not require Direct support.
+
+`read` returns one page; `drain` follows `has_more` immediately. Named consumers
+advance only on explicit acknowledgement. `watch` accepts SSE or JSON fallback,
+skips unknown event types, deduplicates up to 10,000 event IDs per invocation, and
+never rewinds its cursor on a duplicate. JSON pagination has its separate
+`maxPages` bound (default 1000), without consuming reconnect attempts. Reconnects
+are bounded (default 4); exhaustion is explicit `reconnect_exhausted`.
+
+`lastEventId` takes precedence over the starting cursor. On reconnect the watcher
+sends `Last-Event-ID`. `onPartial` is display-only: a null value clears unfinished
+text on completion/disconnect; never execute or reason from an incomplete delta.
+Messages are actionable only after a complete `message` event. SSE frames and
+JSON fallback are limited to 1 MiB, streams to 16 MiB, and partial text per stream
+to 1 MiB. UTF-8 fragmentation and CR/LF/CRLF are supported.
+
+`cursor_expired` is an explicit history gap. Inform the user, then reset a named
+consumer and reread retained history, or supply `onHistoryGap` returning true.
+Automatic recovery is limited to one reset per watch; it does not recover missing
+events. Checkpoints and pending sends survive process restart with durable stores.
+Send retries keep their original connection, issuer, endpoint, ID, body and read
+parameters. Abort signals are invocation-local and are never persisted. Canceling
+delivery does not cancel an accepted company action or prove a lost send failed.
+
+## Node transport
+
+`createNodeTransport` uses Node HTTPS agents, with separate discovery, JSON and
+stream pools. Defaults: 8 pools total, 2 connections per pool (including pending
+TLS), 32 active operations, 15-second JSON timeout, and 5-second discovery timeout.
+There is no hidden request queue: excess pool capacity fails `overloaded`, so a
+later attempt performs fresh DNS and policy checks. Hosts decide scheduling.
+Streams use `transport.stream` with a 5-minute/16-MiB lifetime budget. Call
+`transport.close()` to cancel outstanding reads, DNS waiters, connects and streams.
+
+Every request rechecks DNS and current address policy before pool assignment.
+Changed approved addresses retire incompatible pools; actual TLS peers and reused
+sockets are checked before HTTP bytes. TLS certificates remain verified. Only
+explicit hostname/address exceptions permit private peers. Discovery never carries
+credentials and follows only HTTPS redirects; credential-bearing requests never
+follow redirects. Pool retirement may interrupt an active stream; reconnect uses
+the durable cursor and fresh authorization.
+
+Metadata caching remains bounded and honors freshness, Age, validators, no-cache
+and no-store, with a 300-second upper bound. Expired entries revalidate; 304s retain
+prior caching directives. `resolver.invalidate(target?)` fences old pending cache
+writes without bypassing fetch concurrency/rate limits. J2 rejects changed saved
+issuer/endpoint/resource bindings rather than rerouting persisted work.
+
+## Company service and retention
+
+The server accepts `supportedScopes`, the union offered by its actual sign-in
+methods. `directScopes` remains a compatibility alias. One coordinator must still
+cover authority checks and durable conversation reads/mutations.
+
+Default JSON/request/frame budget is 1 MiB; the maximum encoded event is
+1 MiB minus 1025 bytes. Page sizing reserves 1024 bytes for worst-case IDs, cursors
+and envelopes and counts UTF-8 bytes. Company events and client messages that
+cannot fit are rejected before commit; no receipt/work survives a rejected write.
+Do not reduce configured budgets below those used for retained accepted events.
+
+Notifications are post-commit hints. Subscribe before reading; reconcile durable
+state on wake or every 1000 ms by default. `createConversationNotifications` is
+local acceleration only. Multiple processes work without a broker through targeted
+SQLite reconciliation; deployments can implement the same notification contract
+with their own distributed adapter. Lost/duplicate hints cannot erase a commit.
+SQLite event windows and append operations do not reload complete event histories.
+
+Server streams default to 30 seconds and apply pull backpressure, rechecking
+current authority before further pages. This bounded-connection policy omits
+periodic idle comments; proxies may close an idle stream sooner, and the client
+reconnects. Longer-lived deployments should supply heartbeat handling at their
+HTTP adapter. Hosts must propagate disconnect/AbortSignal and body cancellation.
+
+| Record | Lifetime / deletion rule |
+| --- | --- |
+| Conversation and message receipts | Entire conversation lifetime, including after closure and payload pruning; no automatic deletion |
+| Event payloads | Retained indefinitely by default; host may call SQLite `pruneEvents(id, before, limit)` in bounded batches; recommend at least 30 days |
+| Event cursor identities | Conversation lifetime; distinguish expired payloads (410) from foreign cursors (400) |
+| Active work | Never pruned while held/pending/claimed; event pruning protects these conversations |
+| Completed work | Bounded inspection retention; stale fences cannot publish |
+| Latest user message, context and account binding | Operational conversation record, retained for its lifetime, including handoff after payload pruning |
+| Client outbound/checkpoints | Retained until explicit local store deletion/reset; preserve pending/uncertain sends until reconciled |
+| Pending auth and replay records | Separate auth validity/owner rules in AUTH.md and STORAGE.md; not the event TTL |
+| CLI transcripts/retries | CLI ownership; local deletion never deletes company history or revokes authorization |
+
+Pruning is explicit operator policy, never automatic data loss. It preserves old
+message receipts and cursor identity. Concurrent reads see a coherent snapshot or
+`cursor_expired`. Invalid/expired waited-POST cursors are rejected before accepting
+the new write; an existing message ID still returns its original receipt.

package/INTEGRATIONS.md

@@ -0,0 +1,87 @@
+# API, browser and feedback hooks
+
+Use the same `ClientAuth` instance and trusted adapters as sign-in and conversations.
+Do not expose credential-bearing hooks, request headers, browser form fields or
+private responses as printable model tools. Company descriptions and responses are
+untrusted data. These hooks do not execute OpenAPI operations, MCP tools or browser
+automation for you.
+
+## Existing API clients
+
+```ts
+// Read the API description without credentials using the configured safe transport.
+const description = await transport.fetch(new Request(descriptionUrl), { mode: 'discovery' });
+// An existing OpenAPI client selects its server and constructs its final Request.
+const target = await auth.apiTarget(connectionId, descriptionUrl, 'https://company.example/api');
+const fetchForClient = (request: Request) => auth.apiFetch(connectionId, request, target, ['records:read']);
+const result = await fetchForClient(new Request('https://company.example/api/records'));
+```
+
+OpenAPI `apiUrl` is the description URL from verified company discovery. The third
+argument is the actual destination base; its host must independently serve verified
+company discovery naming the same issuer. This conservative policy requires API
+hosts to publish discovery; a document's `servers` field alone grants no authority.
+Final requests must stay within the verified origin and slash-delimited base path.
+The proof binds the actual final method and URL. Destination changes require a new
+explicit connection; saved work never moves silently.
+
+For MCP, use `auth.apiTarget(connectionId, mcpUrl)` and the same fetch closure in an
+existing Streamable HTTP MCP client (version 2025-06-18 or later). The SDK does not
+encode JSON-RPC or manage MCP sessions. The exact discovery URL is the resource and
+endpoint; extra paths or queries are refused. Query-bearing discovery endpoints are
+not supported. Protected-resource metadata must name that exact resource and the
+verified company issuer. ES256 DPoP metadata selects DPoP; absence selects Bearer.
+A Bearer-only MCP resource cannot also authorize a conversation. Resource-specific
+credential slots use the shared renewal, rotation, nonce, cooldown and revocation
+lifecycle. The wire `token_type` must match verified metadata; there is no fallback
+from DPoP to Bearer. Redirects never forward tokens or proofs. Auth 401 rejection may
+cause one fresh-token retry; unknown results are not automatically retried.
+
+## Agent-controlled browser
+
+```ts
+await auth.joinBrowser(connectionId, 'https://company.example/account', {
+  kind: 'agent-controlled',
+  async postForm({ url, fields, validateRedirect }) {
+    // Bind your existing browser controller here. It must enforce this contract:
+    // isolated per-session storage; verified TLS/actual peer addresses; no logging;
+    // top-level form POST; intercept redirects BEFORE following or replaying a body.
+    const response = await controlledBrowser.postFormWithoutFollowing(url, fields);
+    const destination = validateRedirect(response.status, response.location);
+    await controlledBrowser.navigateWithoutPostBody(destination);
+  },
+});
+```
+
+`controlledBrowser` is the host's existing controller, not an SDK driver. This hook
+is trusted code. Its network layer must reject loopback/private/link-local actual
+connected addresses unless narrowly configured, validate TLS and enforce redirect
+interception. Never replay the assertion on 307/308 or send it in a URL. The supplied
+validator permits only 303 to the exact validated `returnTo`. HttpTransport cannot
+enforce network policy inside an unrelated browser engine. Keep this capability
+separate from the human consent-browser opener. Never join the user's browser.
+Use separate cookies/local storage for each session/user, join just before browsing,
+rejoin on lost recognition and close the context when the session ends. Custom
+controllers own those guarantees; the SDK validates the assertion destination and
+navigation contract but cannot inspect their internal browser implementation.
+
+## Feedback
+
+```ts
+await auth.feedback(connectionId, {
+  kind: 'missing', task: 'Export records',
+  description: 'There is no export operation in the API, conversation or website.',
+});
+```
+
+Signed-out sessions are allowed and no account scope is required. Task and
+description are nonempty strings of at most 200 and 2000 Unicode codepoints. Only
+`missing` is supported client-side. Omit identifiers, personal data and secrets;
+report task limitations rather than individual errors. Success is an empty 202.
+There are no automatic POST retries (including nonce/auth rejection). A lost
+response can mean accepted; callers decide whether to repeat because the protocol
+defines no deduplication key. Prefer one report per unfulfilled task.
+
+The executable generic caller/controller fixtures are `tests/integrations.test.mts`.
+They exercise the same hooks used by the CLI; installed CLI integration is
+verified separately against immutable candidate tarballs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PoppyKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROVIDER.md

@@ -0,0 +1,99 @@
+# Optional identity provider
+
+Import `createProvider`, `createProviderClient`, and `createResultCipher` from
+`@poppykit/client/provider`; durable `SqliteProviderStore` is separately exported
+from `@poppykit/client/provider/sqlite`. Neither is loaded by the core import.
+This is PoppyKit provider contract **v1**, not a Personal Agent Protocol extension.
+Node 24.12+ is required for the SQLite reference adapter.
+
+An operator supplies HTTPS hosting, a provider client metadata URL, JWKS URL,
+HTTPS callback URL on that same domain, an ES256 signer/KMS, a verified company
+metadata resolver, authenticated enrollment and encrypted callback-result storage.
+The provider has no company account-token vault, token-exchange proxy, login UI,
+deployment dependency or cloud dependency.
+
+```js
+import { createProvider, createResultCipher } from '@poppykit/client/provider';
+import { SqliteProviderStore } from '@poppykit/client/provider/sqlite';
+const provider = createProvider({
+  clientId: 'https://identity.example/client.json',
+  jwksUri: 'https://identity.example/jwks',
+  callbackUrl: 'https://identity.example/callback', clientName: 'Operator agent',
+  store: new SqliteProviderStore('/private/provider.sqlite'),
+  cipher: createResultCipher(await operatorKeys.readResultEncryptionKey()),
+  signer: operatorKeys.signer, metadata: verifiedCompanyResolver,
+  authenticateEnrollment: async request => {
+    // Authenticate the human using the operator's existing login; validate CSRF.
+    const human = await operatorLogin.authenticateEnrollment(request);
+    return human ? { subject: human.stableSubject, allowedCompanies: human.companyDomains } : null;
+  },
+  verifySession: binding => operatorSessionVerifier.owns(binding),
+});
+// Route Fetch Requests under /v1/{operation}, plus the exact public URLs above:
+// await provider.handle(request)
+```
+
+`operatorKeys`, `operatorLogin`, `operatorSessionVerifier` and
+`verifiedCompanyResolver` are operator-owned adapters, not globals supplied by
+the package. A session verifier must independently verify both the provider client
+and derived UserID; an opaque session ID alone does not prove ownership. Browser
+signing fails closed without that verifier. Starting a session signs a derived
+UserID assertion; the company checks session/client/UserID association on renewals.
+
+POST JSON operations use `version: 1` and `installationId`. Enroll additionally
+takes a fresh `idempotencyKey`; private operations carry `Authorization: Bearer
+<enrollmentId.secret>`. The secret is generated once and delivered only in that
+authenticated enrollment response. A repeated enrollment key returns `consumed`;
+lost credential delivery requires fresh human authentication and enrollment.
+Installations have independent credentials and callback operations. Re-enrollment
+can recover a visitor identity through the same authenticated operator subject,
+but cannot recover another installation's result. Enrollment never accepts caller
+subjects, arbitrary audiences, lifetimes, key IDs, raw bytes or signing claims.
+
+`identity` takes domain and exact issuer; `begin` registers immutable operation,
+issuer/domain, purpose (`session`, `client-authentication`, `browser`, `direct`),
+optional session and browser return destination. Company metadata is independently
+resolved and enrollment company policy checked. `assert` takes operation/purpose
+only and constructs a 60-second assertion with fresh 256-bit jti. Browser assertions
+are audience-bound to the verified browser endpoint. `createProviderClient` binds
+enrollment credentials and automatically registers SDK assertion operations.
+
+Direct sign-in uses SDK-generated 256-bit state. Trusted CLI code privately
+registers it with `beginDirect` after SDK preparation and before displaying the
+authorization URL. Only its hash is indexed. The callback accepts state, exact
+issuer, and exactly one code/error; result ciphertext is sealed atomically with
+the immutable binding. Identical pending callbacks are harmless; conflicting,
+canceled, expired and consumed callbacks fail. `takeResult` requires enrollment,
+installation, operation, issuer and exact session; it consumes within the same
+SQLite transaction before returning private callback data. Lost retrieval delivery
+is uncertain, never a reason to exchange or retrieve again. SDK code owns PKCE and
+the exchange. Never log request URLs or responses on this route.
+
+SQLite serializes writers across processes. Provider transactions must be
+synchronous, targeted and atomic; custom stores implement `ProviderStore` with
+the same guarantees. The AES-GCM result key comes from an independent secure
+backend and must never be stored beside the database. Cipher failures roll back
+consumption. KMS failures fail closed; a revoke/cancel racing signing is rechecked
+before delivery. External stores/KMS are separate failure boundaries.
+
+Defaults bound enrollments globally to 10,000, pending operations to ten per
+enrollment, assertions to 60/minute, operation lifetime to ten minutes and request
+bodies to 16 KiB. A hard cap of 1,000 retained operations per enrollment keeps
+quota/cleanup/revocation scans complete even under tombstone flooding. Expired
+operations are cleaned in bounded batches on begin;
+tombstones survive expiry plus 30 seconds. Hosts must additionally enforce
+per-human enrollment rate limits, ingress rate/connection/time limits, total
+database retention, and authenticated account recovery. Rate-limit responses
+include a retry timestamp. Errors contain fixed codes only.
+
+Rotate signer configuration only after publishing the new key. Supply
+`publishedKeys` during rotation and retain old public keys until every assertion
+expires plus 30-second skew; never publish private JWK fields. The operator owns
+the publication grace period and KMS key lifecycle.
+
+Enrollment revocation stops new signing/retrieval and cancels pending results.
+It cannot invalidate delivered assertions, existing company Session Tokens,
+Account Tokens or DPoP keys. Revoke company authorization **before** disabling
+provider signing, or use authenticated company account controls afterward.
+This is scoped authority, redaction and provider key custody; it does not isolate
+authority from unrestricted programs running as the same OS user.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# PoppyKit client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for personal-agent providers integrating [Personal Agent Protocol
+draft 0.2](https://personalagentprotocol.org/docs/0.2/spec). Discover companies,
+start sessions, use Direct/Device/Mediated sign-in, exchange JSON/SSE conversations,
+authorize API requests, join an agent browser and send feedback. Your application
+supplies the agent and trusted infrastructure.
+
+## Installation
+
+Requires Node **24.12.0 or later**, ESM and HTTPS. CI certifies Node 24.12.0;
+later majors are not separately certified. Optional SQLite uses experimental
+`node:sqlite` and local filesystem locking.
+
+Version **0.1.0** is an initial development release candidate under the [MIT license](LICENSE).
+It has not been published. Install a verified tarball:
+
+```sh
+npm install ./poppykit-client-0.1.0.tgz
+```
+
+The only production dependency is `jose@6.2.12`. No server SDK or CLI is required.
+Registry installation instructions will accompany the first public release.
+
+## Quickstart
+
+Discovery needs no signing key, account token or database:
+
+```js
+import { createMetadataResolver, createNodeTransport } from '@poppykit/client';
+
+const transport = createNodeTransport();
+try {
+  const company = await createMetadataResolver(transport).resolveCompany('company.example');
+  console.log(company.document.organization);
+} finally {
+  transport.close?.();
+}
+```
+
+Replace `company.example` with a company publishing draft 0.2 discovery.
+Run the complete [quickstart](examples/quickstart.mjs) with a real domain, or
+`node examples/quickstart.mjs --self-check` for a deterministic offline example.
+
+## Configuration and authentication
+
+`createClientAuth(options)` owns sessions, all three sign-in methods, renewal,
+scope replacement, sign-out and recovery. Supply `namespace`, `localUserId`,
+`clientId`, registered `redirectUris`, an `AuthStore`, `SecretStore`, safe transport
+and metadata resolver. Run `recover()` at startup. Publish HTTPS client metadata
+and public JWKS; private signing keys stay in your signer or provider.
+
+Choose an `IdentitySigner`, or authenticated `AssertionProvider` and
+`ProviderIdentity` adapters. The optional `/provider` reference is documented in
+[PROVIDER.md](PROVIDER.md). Operators supply HTTPS hosting, enrollment authentication,
+company policy and signing/KMS. Anonymous sessions require a separate local signer
+with a published key; provider-only custody reports `anonymous_unavailable`.
+
+Call `start(domain)`, then `authorization(connectionId, scopes)` to inspect grants,
+missing scopes and advertised methods. `beginSignIn(connectionId, { method, scopes })`
+selects `direct`, `device` or `mediated`. Direct requires an authenticated browser
+binding and HTTPS callback. Device displays a verified human link/code and resumes
+with `continueSignIn`. Mediated invokes your `TrustedInput.collect` UI. Keep that UI,
+passwords, codes and credential adapters outside model tools. See [AUTH.md](AUTH.md)
+for partial consent, scope upgrades, cancellation and revocation.
+
+## Examples and common operations
+
+Configure conversations using the verified target and the same auth lifecycle:
+
+```js
+import { createConversationClient } from '@poppykit/client';
+const target = await auth.target(connectionId);
+const conversations = createConversationClient({
+  ...target, connectionId, store: conversationStore, clock: { now: Date.now },
+  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
+  authorization: (id, scopes) => auth.authorization(id, scopes),
+});
+```
+
+`auth`, `connectionId` and `conversationStore` are your configured instances.
+`start`, `send`, `read`, `watch`, `ack`, `handoff` and `close` manage the lifecycle.
+Retain message IDs for retries; acknowledge durable deliveries after processing.
+[DELIVERY.md](DELIVERY.md) explains cursors, streaming, pagination and retention.
+
+Use `apiTarget`/`apiFetch` with an existing OpenAPI or MCP client. The final URL
+must be independently authorized; an OpenAPI `servers` entry grants no authority.
+`joinBrowser` accepts a trusted agent-controlled controller separate from human
+consent. `feedback` sends a single `missing` report expecting empty HTTP 202.
+[INTEGRATIONS.md](INTEGRATIONS.md) documents the adapter contracts and examples.
+
+## Errors, cancellation, retries and limits
+
+Handle `AuthFailure.code` and `ConversationError.code`; do not parse messages or
+log credential headers/private adapter errors. Pending operations are resumable;
+an uncertain remote exchange requires reconciliation and is never silently replayed.
+Declined upgrades preserve old access; sign-out never automatically reconnects.
+
+Conversation operations accept `AbortSignal`. Cancellation cannot undo bytes sent.
+Conversation retries retain message IDs/payloads with bounded backoff and Retry-After.
+Auth deadlines persist across restarts. Feedback has no automatic POST retry or
+deduplication promise. Pools, bodies, event/page sizes and reconnects are bounded;
+see [DELIVERY.md](DELIVERY.md). External effects need application idempotency.
+
+## Storage and production responsibilities
+
+Optional `/sqlite` exports `SqliteAuthStore` and `SqliteConversationStore`;
+`/memory` exports non-durable `MemoryConversationStore`. Consumers can implement
+the targeted contracts using their own databases. Store Account Tokens, DPoP keys
+and PKCE in a secure `SecretStore`; Session Tokens stay in memory. SQLite stores
+secret references and private message data, not vault encryption. Database, vault
+and remote exchange are separate boundaries; implement orphan-secret reconciliation
+and deployment ownership checks. [STORAGE.md](STORAGE.md) defines atomicity,
+recovery and explicit development reset.
+
+## Reference and support
+
+[API.md](API.md) maps public exports and TypeScript declarations to deeper guides.
+This independent draft implementation has deterministic and packaged tests;
+production vaults, browsers, external issuers and hosting need operator validation.
+Individual protocol extensions and application business logic are outside the SDK.
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),
+[CHANGELOG.md](CHANGELOG.md) and [RELEASING.md](RELEASING.md). No public license grant
+has been selected; publication remains blocked pending the owner's license decision.