@poppykit/client 0.4.0 → 0.5.0

package/API.md

@@ -5,9 +5,10 @@ for complete option/result types. This map describes the supported integration s
 
 | Entry point | Main exports | Guide |
 | --- | --- | --- |
-| `@poppykit/client` | `createMetadataResolver`, `createNodeTransport` | [README](README.md), [delivery](DELIVERY.md) |
+| `@poppykit/client` | `createMetadataResolver`, `signInMethods`, `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` | `Author`, `AuthorType`, `Message`, `RecordedMessage`, conversation/event types | [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) |
@@ -17,7 +18,7 @@ for complete option/result types. This map describes the supported integration s
 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
+`joinBrowser`, `feedback` and `excludedTasks`. 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

package/AUTH.md

@@ -5,9 +5,34 @@ 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.
 
+Each `start` creates a new Session Key; only the issuer-specific User ID is reused.
+Renewal uses that Session Key. `Connection.sessionId` remains a local identifier
+for the key's lifetime, not the company's internal Session ID. Token requests
+carry no `session_id`, and token responses need neither it nor `signed_in`.
+The grant determines sign-in state. Omitted signed-in scope inherits the request's
+scope context; an explicit response can narrow it but cannot expand it.
+
+After a refresh returns definite `invalid_grant`, the client diagnoses the Session
+with a signed-out assertion before discarding the Account Token. A live Session
+means the Account Token is unusable. An ended key is retired durably before a fresh
+key attempts replacement. Ambiguous refresh responses remain uncertain and are
+never resent. Sign-out still disconnects locally before remote cleanup.
+
+Discovery accepts only draft 0.3, checks the final well-known path (including
+cache revalidation), exact issuer and reciprocal `protected_resources`.
+`signInMethods(metadata)` derives Direct/Device from issuer grants and endpoints
+and uses `scopes_supported`; Mediated keeps `auth.mediated.scopes`. Company scope
+names cannot start with `poppy:`. Descriptions come from `auth.scopes` or a listed
+OpenAPI document. Prefer Direct when the user can receive its callback; Device is
+for appropriate device-flow situations. No sign-in method is user consent.
+
 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.
+and advertised methods, with `scopeDescriptions` from `auth.scopes`. Choose a method explicitly in `beginSignIn`. Direct
+requires a registered HTTPS callback on the client domain, or an RFC 8252 HTTP
+loopback IP callback (`127.0.0.1` or `[::1]`), and an authenticated browser binding.
+Only a loopback registration's port may vary; callback completion and code exchange
+use the exact port selected at initiation. Metadata/network endpoint address
+protections do not change. The URL's `dpop_jkt` binds the code to this Session Key.
 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`

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.0 — 2026-10-28
+
+Target pinned Personal Agent Protocol draft 0.3. Break discovery, Session Key/token, author, browser-controller and feedback contracts; retain explicit storage subpaths. Upgrade normalized auth state 1→2; stop old writers and reset incompatible conversation/outbox state before cutover.
+
+Local migration candidate only. Publication and deployment require separate approval.
+
+## 0.4.1
+
+Support Node 24.21.0 and later within Node 24 under the owner-accepted runtime policy.
+Build, verification and publication tooling read .node-version.
+
 ## 0.4.0
 
 Require Node 24 >=24.22.1 within 24.x. Accept conforming OAuth callback fields,

package/CONTRIBUTING.md

@@ -1,11 +1,13 @@
 # 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.
+Follow the pinned draft 0.3 [specification](https://personalagentprotocol.org/docs/0.3/spec)
+and [guides](https://personalagentprotocol.org/docs/0.3/guides). Tests/snapshots are
+supporting evidence. This unreleased checkout has completed only the discovery
+stage of migration; auth, wire/storage and integrations still need their stages.
+Demo/business workflows and individual extensions are excluded.
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
-Use Node 24.22.1, TypeScript 5.9.3 and @types/node 24.10.0.
+Use Node 24.21.0, TypeScript 5.9.3 and @types/node 24.10.0.
 Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile --ignore-scripts.
 
 ```sh

package/DELIVERY.md

@@ -1,6 +1,6 @@
 # Conversation delivery and transport
 
-The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
+Conversation messages and authorization events now use draft 0.3. Company content, messages,
 unknown events and partial text remain untrusted data for the host application.
 
 ## Client
@@ -92,3 +92,16 @@ 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.
+
+## Unreleased draft 0.3 breaking change
+
+Messages now require `author: { type: 'agent' | 'human' }`; protocol `sender` is
+unsupported. Human text must remain the person's exact words. Company authors
+may include `id`, `name` and an HTTPS `image`. Authorization events now contain
+`error: 'insufficient_scope'` and nonempty required `scope`.
+
+No backward compatibility is provided. Stop writers and explicitly reset old
+history, outboxes, checkpoints and caller retry handles before cutover, preserving
+configuration. Old pending `sender` requests fail `legacy_message_uncertain`
+without dispatch or mutation. Reconcile uncertain delivery before clearing it;
+never rebuild the body or allocate a replacement ID to hide uncertainty.

package/INTEGRATIONS.md

@@ -32,8 +32,11 @@ endpoint; extra paths or queries are refused. Query-bearing discovery endpoints
 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
+credential slots use the shared nonce, cooldown and revocation
+lifecycle. Bearer-only MCP credentials come only from Token Exchange of a current
+DPoP Session Token, preserving its Session and limiting scopes to that subject. The
+issuer must advertise the exchange grant; exchange does not rotate the Account Token.
+DPoP-capable MCP keeps the normal token grants. 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.
 
@@ -42,6 +45,12 @@ cause one fresh-token retry; unknown results are not automatically retried.
 ```ts
 await auth.joinBrowser(connectionId, 'https://company.example/account', {
   kind: 'agent-controlled',
+  async loadJoinForm(url) {
+    // Top-level GET in this isolated browser; verify the final URL and form action
+    // are exactly url. Read the hidden code only here, outside model context.
+    return controlledBrowser.loadJoinForm(url);
+  },
+  navigate: url => controlledBrowser.navigateWithoutPostBody(url),
   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;
@@ -56,13 +65,15 @@ await auth.joinBrowser(connectionId, 'https://company.example/account', {
 `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
+interception. Never replay the code or proof on 307/308 or send it in a URL. The supplied
+validator permits only 303 to an HTTPS company page. After that redirect, the SDK
+asks the controller to navigate to the 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
+controllers own those guarantees; the SDK signs a Session Key proof with the form
+code as nonce (no access token or identity assertion), and validates the destination and
 navigation contract but cannot inspect their internal browser implementation.
 
 ## Feedback
@@ -77,7 +88,11 @@ await auth.feedback(connectionId, {
 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.
+report task limitations rather than individual errors. Success is an empty 202
+(returning undefined) or HTTP 200 with an `Alternative`. The SDK validates the latter
+and returns instructions/references as company data, never as user consent. Unlisted
+OpenAPI/MCP references and unknown reference types are ignored; known malformed
+references fail. Web links must be HTTPS. No alternative is executed automatically.
 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.
@@ -85,3 +100,18 @@ 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.
+
+## Task metadata
+
+Call `auth.excludedTasks(connectionId)` before choosing how to perform a task.
+It uses `MetadataResolver.resolveExcludedTasks(document)` (optional for custom
+resolvers), fetches the advertised document without credentials and shares the
+resolver's bounded HTTP cache/revalidation. Alternatives use the feedback validator;
+cached references are checked against current discovery on every read.
+
+Discovery exposes `auth.scope_hints`: both fields are required, unknown changes
+become irreversible, and unknown fields are ignored. Missing hints remain unknown.
+Hints and excluded task phrases are company claims, never user approval. The host
+agent decides whether a phrase matches its task. The SDK/CLI intentionally omit the
+SHOULD-level automatic pre-task check: they have no task planner; callers choose
+when to read the metadata. No task-policy engine or alternative executor is supplied.

package/PROVIDER.md

@@ -14,7 +14,7 @@ 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.
 The wire protocol remains PoppyKit provider **v1**; the 0.2 TypeScript API uses async storage, not a Personal Agent Protocol extension.
-Node 24.x (at least 24.22.1) is required for the SQLite reference adapter.
+Node 24.x (at least 24.21.0) 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
@@ -75,7 +75,6 @@ const provider = createProvider({
     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)
@@ -99,11 +98,11 @@ but cannot recover another installation's result. Enrollment never accepts calle
 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
+issuer/domain, purpose (`session`, `client-authentication`, `direct`) and Direct Session Key binding. 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
+only and constructs a 60-second assertion with fresh 256-bit jti. Browser-purpose
+operations/assertions and verifySession are removed; browser joining uses the
+locally held Session Key and browser-bound form code. `createProviderClient` binds
 enrollment credentials and automatically registers SDK assertion operations.
 
 Direct sign-in uses SDK-generated 256-bit state. Trusted CLI code privately
@@ -112,7 +111,10 @@ 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
+installation, operation, issuer and exact `sessionKey` thumbprint from the SDK's
+authorization URL `dpop_jkt`; the local `Connection.sessionId` cannot identify a
+company Session. Old Direct operations without the key binding must restart.
+Retrieval consumes within the same
 storage 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.

package/README.md

@@ -1,14 +1,21 @@
 # PoppyKit client
 
-TypeScript SDK for [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec):
+Draft 0.3 migration (2026-10-28), pinned to the public source captured that day.
+Client/CLI 0.5.0 and server 0.4.0 break the earlier protocol contracts. Stop old
+writers and follow the documented storage/reset procedure before compatible
+writers resume. Registry, deployment and live acceptance have separate receipts.
+
+The Node 24.21.0 minimum is an owner-accepted compatibility baseline. Use a current patched Node 24 runtime where available; this minimum does not establish that older runtimes contain later security fixes. Build and release CI read `.node-version`.
+
+TypeScript SDK for [Personal Agent Protocol draft 0.3](https://personalagentprotocol.org/docs/0.3/spec):
 discovery, authentication, conversations and API/browser/feedback hooks. Your
 application supplies the agent and trusted infrastructure. [MIT](LICENSE).
 
 ## Install
 
-This source contains unreleased repairs; final version selection and publication are pending.
+Use the exact version verified by its protected release workflow; check registry publication before installation.
 
-Requires Node **24.x, at least 24.22.1**, ESM and HTTPS. CI tests Node 24.22.1 on Linux, macOS and
+Requires Node **24.x, at least 24.21.0**, ESM and HTTPS. CI tests Node 24.21.0 on Linux, macOS and
 Windows; other Node majors are unsupported.
 
 ```sh
@@ -18,7 +25,7 @@ npm install @poppykit/client
 ## Discover a company
 
 No credentials or database are needed. Replace `company.example` with a company
-publishing draft 0.2 discovery:
+publishing draft 0.3 discovery:
 
 ```js
 import { createMetadataResolver, createNodeTransport } from '@poppykit/client';

package/RELEASING.md

@@ -6,7 +6,7 @@ changing runtime APIs. Each new version needs its own source/artifact evidence.
 
 ## Before tagging
 
-- Confirm npm ownership, unused versions, supported Node 24.x (at least 24.22.1) and npm>=11.5.1.
+- Confirm npm ownership, unused versions, supported Node 24.x (at least 24.21.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.

package/STORAGE.md

@@ -1,8 +1,8 @@
 # Persistence and recovery
 
-Use targeted storage contracts. Node 24.x, at least 24.22.1, is required. The optional `@poppykit/client/sqlite` entry point exports
+Use targeted storage contracts. Node 24.x, at least 24.21.0, is required. The optional `@poppykit/client/sqlite` entry point exports
 `SqliteAuthStore` and `SqliteConversationStore`; importing the client core does not
-load SQLite. `node:sqlite` is experimental in the tested Node 24.22.1 runtime.
+load SQLite. `node:sqlite` is experimental in the tested Node 24.21.0 runtime.
 Consumers can implement `AuthStore` and `ConversationStore` using their own database.
 
 ```ts
@@ -88,6 +88,18 @@ recovery of a token that the issuer rotated but never delivered.
 
 ## Development reset
 
+Normalized auth state version 1 upgrades to version 2 atomically on first access
+in both SQLite and PostgreSQL, under the namespace's writer lock. Stop old SDK
+processes before opening the candidate adapters; mixed-version writers are not
+supported. This is a record upgrade, with no SQL schema change. Owner, epoch,
+stable User IDs, grants, scopes, cleanup and internal connection/operation IDs stay.
+Legacy connections discard their volatile token slots and require a fresh key on
+next renewal. Old shared-key references remain retained, but are never used for
+another token request. Prepared old operations are cancelled; dispatched/staged
+ones still pass through `recover()`, preserving rotated tokens and uncertainty.
+Custom targeted adapters must provide the same complete-namespace upgrade under
+their writer lock; the client's fallback also upgrades whole-state snapshots.
+
 There is no automatic migration from old whole-state development stores. Stop all
 users of a disposable store, resolve uncertain remote outcomes, and explicitly move
 aside its database and WAL/SHM files and the matching host-managed secret namespace
@@ -110,7 +122,7 @@ never deletes company history, revokes access or cancels accepted business work.
 The optional `@poppykit/client/postgres` exports `PostgresAuthStore` and
 `PostgresConversationStore`; `/provider/postgres` exports `PostgresProviderStore`.
 Install the optional peer `pg@8.23.1` only when choosing these subpaths.
-Protocol-only imports load neither pg nor SQLite. PostgreSQL 17 and Node 24.x (at least 24.22.1)
+Protocol-only imports load neither pg nor SQLite. PostgreSQL 17 and Node 24.x (at least 24.21.0)
 are supported; plain PostgreSQL and Supabase transaction pooling use the same adapter.
 There is no Supabase Auth or application dependency.
 

package/dist/adapter-contract.js

@@ -6,7 +6,7 @@ export function runClientConversationAdapterContract(fixture) {
         const f = await fixture();
         try {
             const key = { connectionId: 'contract', issuer: 'https://issuer.example/one', endpoint: 'https://company.example/conversations' };
-            const row = { ...key, id: 'message', fingerprint: 'original', phase: 'pending', target: null, request: { message: { id: 'message', sender: 'agent', text: 'hello' } } };
+            const row = { ...key, id: 'message', fingerprint: 'original', phase: 'pending', target: null, request: { message: { id: 'message', author: { type: 'agent' }, text: 'hello' } } };
             const saved = await Promise.all([f.store.prepareOutbound(key, row), f.second.prepareOutbound(key, { ...row, fingerprint: 'changed' })]);
             assert.equal(saved[0].fingerprint, saved[1].fingerprint);
             saved[0].request.message.text = 'mutated';

package/dist/auth/client-auth.d.ts

@@ -1,3 +1,4 @@
+import type { Alternative, ExcludedTask } from '../network/tasks.js';
 import type { AuthSelection, AuthStore } from './store.js';
 import type { OperationOwner } from './ownership.js';
 import type { JsonObject } from '../protocol/wire.js';
@@ -22,10 +23,6 @@ export type AssertionRequest = {
     purpose: 'client-authentication';
 } | {
     purpose: 'session';
-} | {
-    purpose: 'browser';
-    sessionId: string;
-    returnTo: string;
 });
 export interface AssertionProvider {
     assert(request: AssertionRequest): Promise<{
@@ -41,6 +38,7 @@ export interface ProviderIdentity {
 }
 export type SignInMethod = 'direct' | 'device' | 'mediated';
 export interface AuthorizationRequirement {
+    scopeDescriptions?: Record<string, string>;
     requiredScopes: string[];
     grantedScopes: string[];
     missingScopes: string[];
@@ -173,7 +171,8 @@ export interface ClientAuth {
     apiTarget(connectionId: string, apiUrl: string, destination?: string): Promise<ApiTarget>;
     apiFetch(connectionId: string, request: Request, target: ApiTarget, requiredScopes?: readonly string[]): Promise<Response>;
     joinBrowser(connectionId: string, returnTo: string, controller: AgentBrowserController): Promise<void>;
-    feedback(connectionId: string, report: FeedbackReport): Promise<void>;
+    feedback(connectionId: string, report: FeedbackReport): Promise<Alternative | void>;
+    excludedTasks(connectionId: string): Promise<ExcludedTask[]>;
 }
 export interface CredentialRecord {
     secretRef: string;
@@ -197,6 +196,7 @@ export interface ConnectionRecord {
     slots: Record<string, CredentialRecord>;
     anonymous?: boolean;
     notBefore?: string;
+    needsSessionKey?: boolean;
 }
 export interface GrantRecord {
     id: string;
@@ -239,6 +239,7 @@ export interface OperationRecord {
     method?: SignInMethod;
     requiredExistingScopes?: string[];
     signInSessionId?: string;
+    signInSessionKey?: string;
     device?: {
         codeRef: string;
         intervalMs: number;
@@ -270,7 +271,7 @@ export interface CleanupRecord {
     notBefore?: string;
 }
 export interface ClientAuthState {
-    version: 1;
+    version: 1 | 2;
     epoch: string;
     owner: {
         namespace: string;
@@ -279,7 +280,7 @@ export interface ClientAuthState {
     } | null;
     identities: Record<string, {
         userId: string;
-        dpopKeyRef: string;
+        dpopKeyRef?: string;
     }>;
     connections: Record<string, ConnectionRecord>;
     grants: Record<string, GrantRecord>;
@@ -294,4 +295,6 @@ export declare class AuthFailure extends Error {
     constructor(code: string, connectionId?: string | undefined, retryAfterMs?: number | undefined, retryAt?: string | undefined);
 }
 export declare function initialClientAuthState(): ClientAuthState;
+/** Upgrade a complete namespace under its writer lock; dispatched/staged work still goes through recover(). */
+export declare function upgradeClientAuthState(state: ClientAuthState): void;
 export declare function createClientAuth(options: ClientAuthOptions): ClientAuth;