@poppykit/client 0.0.0-stage → 0.1.1

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,18 @@
+# Changelog
+
+## 0.1.1
+
+Documentation refresh: registry installation, runnable quickstarts, focused guides
+and the tagged GitHub/OIDC release runbook. No runtime API, storage format or
+third-party dependency change.
+
+## 0.1.0
+
+Initial MIT development release, published manually. Discovery, safe HTTPS, all
+three sign-in methods, targeted durable storage and recovery, conversations and
+API/browser/feedback hooks. The CLI uses the client SDK with trusted secure-backend
+adapters. J8 established strict typed tests and exact installed-artifact checks.
+
+Version 0.x may still change APIs/storage; future changes must explain compatibility,
+migration/reset and security implications. No stable 1.0 or external-host certification
+is promised. Older private 0.0.0 candidates retain their own historical evidence.

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Follow the live draft 0.2 [specification](https://personalagentprotocol.org/docs/0.2/spec)
+and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots are
+supporting evidence. Demo/business workflows and individual extensions are excluded.
+Code is [MIT](LICENSE); confirm rights for third-party contributions.
+
+Use Node 24.12.0, TypeScript 5.9.3 and @types/node 24.10.0.
+Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
+
+```sh
+npm run typecheck
+npm run build
+npm run typecheck:tests
+npm test
+npm run check:docs
+```
+
+First-party tests/workers/verification helpers are canonical `.mts`. The existing
+compiler checks the whole strict program before emitting ignored adjacent `.mjs`.
+Failed builds remove stale outputs; no loader/type stripping substitutes for checking.
+Run `npm run build:tests` before `node scripts/run-checks.mjs GROUP` (unit, contracts,
+integration, validation). Groups are exhaustive/disjoint. LF source bytes are enforced
+by Git attributes. Generated test code is outside the npm allowlist; production tests
+import built/installed JavaScript. Release/build tools and examples may remain JS.
+
+`npm run coverage` builds production and checked tests, then writes native Node
+line/branch/function reports under `coverage/` (summary.txt, lcov.info, report.json,
+raw/). Metrics cover loaded first-party dist JS: no production source maps or TS
+remapping; node_modules excluded, unloaded modules listed. Raw subprocess reports
+are retained, but arbitrary children may not merge and killed workers may not flush.
+Installed/OS/host checks are separate evidence; no percentage proves conformance.
+
+Include callers, meaningful regression evidence and docs with behavior changes.
+Preserve credential/destination validation, private errors and persisted data.
+Report checks actually run and limits. Use Issues for non-sensitive defects and
+[SECURITY.md](SECURITY.md) for vulnerabilities. Follow [RELEASING.md](RELEASING.md)
+before tagging/publishing; obtain explicit owner authorization.

package/DELIVERY.md

@@ -0,0 +1,94 @@
+# 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. The auth lifecycle rejects changed saved
+issuer/endpoint/resource bindings rather than rerouting persisted work.
+
+## Peer retention
+
+The [server delivery guide](https://github.com/LMol-4/poppykit-server/blob/main/DELIVERY.md)
+describes service configuration, byte budgets, notifications and bounded streams.
+Keep the following distinct lifetimes when choosing an operator retention policy:
+
+| 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,50 @@
-# 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 Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec):
+discovery, authentication, conversations and API/browser/feedback hooks. Your
+application supplies the agent and trusted infrastructure. [MIT](LICENSE).
+
+## Install
+
+Requires Node **24.12.0+**, ESM and HTTPS. CI tests Node 24.12.0 on Linux, macOS and
+Windows; later majors are not separately certified.
+
+```sh
+npm install @poppykit/client@0.1.1
+```
+
+## Discover a company
+
+No credentials or database are needed. Replace `company.example` with a company
+publishing draft 0.2 discovery:
+
+```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?.();
+}
+```
+
+The packaged [quickstart](examples/quickstart.mjs) also supports `--self-check`
+without a network service.
+
+## Guides
+
+- [Authentication](AUTH.md): sessions, Direct/Device/Mediated, consent, renewal and revocation.
+- [Storage](STORAGE.md): targeted adapters, secret references, recovery and explicit resets.
+- [Delivery](DELIVERY.md): messages, streaming, cancellation, retries and retention.
+- [Integrations](INTEGRATIONS.md): verified API targets, agent browser and feedback.
+- [Optional provider](PROVIDER.md): operator-hosted signing and callback custody.
+- [API exports](API.md), [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+  [changelog](CHANGELOG.md) and [releasing](RELEASING.md).
+
+Keep Account Tokens, DPoP keys and PKCE in a secure SecretStore; never expose them
+to model tools. An uncertain remote result must not be silently replayed. SQLite
+is optional/experimental and is not vault encryption. Production issuers, vaults,
+browsers and hosting require operator validation; individual extensions and
+application business workflows are outside this SDK.

package/RELEASING.md

@@ -0,0 +1,91 @@
+# Releasing
+
+Use the tagged GitHub Actions workflow, not a local rebuild. Packages are MIT;
+0.1.0 was manually bootstrapped. Version 0.1.1 refreshes documentation without
+changing runtime APIs. Each new version needs its own source/artifact evidence.
+
+## Before tagging
+
+- Confirm npm ownership, unused versions, supported Node 24.12.0 and npm>=11.5.1.
+  Keep the pinned compiler/dependencies; do not upgrade tooling during a release.
+- Update version, changelog and shipped docs. CLI's client dependency and both
+  candidate JSON files must match exact final SDK versions/full source SHAs.
+- Review the full diff and run typecheck, build, tests and documentation checks.
+  Preserve the existing API/storage/security contracts and historical evidence.
+- Protect source, workflow files, pins and release tags with repository review/rules.
+  All actions are commit-pinned; release verification never restores a PR cache.
+- Verify GitHub environment **npm**: variable **NPM_PUBLISH_ENABLED=true**,
+  intended required reviewer, no admin bypass, and allowed deployment tags **v***.
+  Reviewers approve the real pending deployment; automation must not approve for them.
+- Configure the npm package's GitHub trusted publisher: owner **LMol-4**, this
+  package repository, workflow **release.yml**, environment **npm**. Match case.
+  Enable **direct npm publish** permission; this workflow does not stage a publish.
+  Configure near the release: unused configurations expire after two days. Public
+  source/package visibility and supported GitHub-hosted runners are required for
+  this provenance path. Do not supply NODE_AUTH_TOKEN or fall back to a long-lived
+  token if OIDC fails. Confirm current [npm requirements](https://docs.npmjs.com/trusted-publishers/).
+
+## Publish exact tagged source
+
+Client and server are independent. Publish client before CLI: the CLI registry
+guard requires its tested client tarball integrity to equal the published one.
+
+1. Merge reviewed source to main. Record the full SHA and create/push an approved
+   immutable **vVERSION** tag at that exact commit. Never move or replace a tag.
+
+   ```sh
+   git tag vVERSION FULL_SHA
+   git push origin refs/tags/vVERSION
+   ```
+2. Dispatch **Release** from that tag, with matching version, tag and full commit.
+   Optional `publish=false` rehearses verification only. A later publishing dispatch
+   is a new run with newly identified artifacts; it does not reuse a rehearsal's bytes.
+3. Dispatch with `publish=true` when authorized. Example (replace all placeholders):
+
+   ```sh
+   gh workflow run release.yml --repo LMol-4/PACKAGE --ref vVERSION -f version=VERSION -f tag=vVERSION -f commit=FULL_SHA -f publish=true
+   ```
+
+4. Wait for candidate, fast, contracts, integration, packaged-linux/windows/macos,
+   validation and gate to succeed. Missing, failed, canceled or skipped prerequisites
+   fail closed. Then follow the Actions environment-approval link. Do not bypass it.
+5. The publisher rechecks source/tag/ref/version, trusted manifest digest, unchanged
+   tarball metadata/bytes, owner enablement, registry absence and dependency integrity.
+   It publishes the same-run tested tarball with `--access public --provenance
+   --ignore-scripts`; it never installs, builds or packs again.
+6. Save run URL, full source SHAs, manifest SHA256, filenames, versions, byte counts,
+   tarball SHA256/npm SHA512 and registry integrity/provenance. Download before the
+   14-day candidate retention expires. Verify registry bytes, a clean exact-version
+   registry install, exported modules and the real npm CLI shim.
+
+Ordinary main/tag CI is useful evidence but is not a tagged Release/OIDC publishing
+run. A dry run or green tests alone do not prove npm authentication or provenance.
+The separate checked test-harness artifact is source/output-hash bound, used only
+by unprivileged verification jobs, and never published in an npm package.
+
+## Failure and partial release
+
+Stop on tag/source/version/digest mismatch, unknown registry responses or changed
+client integrity. Do not weaken gates, repack approved bytes, change pins silently,
+force an overwrite or use a token fallback. Inspect the failed job and preserve logs.
+For OIDC/auth failure check publisher spelling/case, workflow/environment identity,
+expiry, reviewer approval, permissions and npm/toolchain support before a new run.
+
+If a version already exists, compare its registry integrity and provenance with the
+saved receipt. Matching successful publication is recorded, never republished.
+For partial publication, finish only absent packages; verify the published client's
+exact bytes before CLI. If bytes differ or a fix is needed, use a reviewed new
+version and complete verification. A source checkout rollback cannot undo an npm
+publication or external side effect. Deprecation, dist-tag changes, unpublish and
+replacement versions need separate owner authorization; never delete evidence.
+
+## Verification limits
+
+Deterministic source suites run once per verification graph on Linux; exhaustive
+file groups reject omissions/duplicates. Packaged jobs test actual installed JS,
+exports/declarations/content/SQLite and representative platform behavior; CLI also
+tests real shims, auth/retry processes and API/browser/feedback wiring. They do not
+certify a production keyring, physical terminal, browser engine, KMS or TLS deployment.
+Windows GNU tar is given archive basename plus directory cwd to avoid drive-colon
+remote parsing. Failure logs retain seven days. Expired/missing artifacts require a
+new full run, not relabeling old results. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security reporting
+
+Do not put credentials, tokens, private keys, personal records or exploit details
+in a public issue. Use this repository's GitHub **Security → Report a vulnerability**
+when private reporting is enabled. If it is unavailable, request a private contact
+from the repository owner without disclosing the vulnerability publicly. The owner
+must enable/confirm that route; no response SLA is promised.
+
+Include affected commit/version, a minimal reproduction using synthetic data,
+impact and the trust boundary involved. These draft packages have no promised
+support window or response SLA. Custom vaults, issuers, browser controllers,
+proxy routing and deployment policy remain operator responsibilities. Redaction
+and scoped authority do not isolate an unrestricted same-user program.