@poppykit/client 0.4.1 → 0.6.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
@@ -28,7 +29,7 @@ The optional Postgres entry point ships its adapters, `createPostgresPool`,
 `postgresMigration`, `migratePostgres` and schema-version export; see [storage](STORAGE.md).
 TypeScript Postgres consumers also install `@types/pg@8.23.1` as a development dependency.
 
-Custom `AuthStore` implementations must honor `AuthSelection.history` as described
+Custom `AuthStore` implementations must honor shared-grant/account aggregation and `AuthSelection.history` as described
 in [STORAGE.md](STORAGE.md). Provider callbacks now acknowledge identical consumed
 results without making `takeResult` reusable; see [PROVIDER.md](PROVIDER.md).
 
@@ -36,3 +37,11 @@ results without making `takeResult` reusable; see [PROVIDER.md](PROVIDER.md).
 `PostgresConnection` type are exported only by `@poppykit/client/provider/postgres`.
 They explicitly enlist provider SQL in a host-owned guarded transaction; the host
 retains commit/rollback, deadline and privilege responsibility.
+
+## Business Operations v2
+
+See [OPERATIONS.md](OPERATIONS.md) for the complete consent/effect contract. Root exports include `BusinessOperation`, `OperationApproval`, `OperationRequest`, `operationsV2`, `supportsOperations`, `parseBusinessOperation`, `parseOperationApproval`, `parseApprovalHeader`, `approvalHeader`, `mcpApproval`, `approvalMetaKey`, `captureApiOperationRequest`, `operationExpiry`, `operationRequiredResponse` and `operationToolError`.
+
+Client exports `createOperationClient`, `createOperationSender`, `OperationClientError`, the three approved-channel serializers, `BusinessClientContext`, `BusinessAttempt`, `BusinessAttemptStore`, `TrustedOperationConsent` and `OperationDelivery`. `ClientAuth.businessContext` supplies a verified binding. SQLite/PostgreSQL subpaths export `SqliteBusinessAttemptStore`/`PostgresBusinessAttemptStore`. The adapter-contract subpath exports `runBusinessAttemptAdapterContract`. Conversation options accept verified `operations:{client,company}` metadata.
+
+For business-operation sends, pass the saved `BusinessClientContext` as the final `expectedContext` argument to `apiFetch`/`authorizedFetch`. Channel sender callbacks receive that context. A changed Company/client/User/account or signed-out Session fails before dispatch; target discovery does not authorize a replacement account. See [Operations](OPERATIONS.md).

package/AUTH.md

@@ -1,67 +1,99 @@
 # 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.
-
-Direct callbacks accept OAuth error details and ignore unknown response fields.
-The registered origin/path/query, browser binding, state and exact issuer still
-have to match; duplicate recognized fields and a simultaneous code/error fail.
-Error descriptions and error URLs are never included in public auth outcomes.
-
-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.
-
-Provider `expiresAt` values are Unix seconds. Session/client assertions and browser
-joins accept a local freshness horizon of 60 seconds plus 30 seconds of clock skew;
-an assertion at or before the local current time is rejected. This freshness check
-does not verify the signed assertion's lifetime: the issuer verifies the signature,
-claims, replay and protocol maximum of five minutes between `iat` and `exp`.
-`provider_clock_skew` and `provider_assertion_expired` suggest checking automatic
-date/time and retrying. `provider_invalid_response`, `provider_unauthorized`,
-`provider_rate_limited` and `provider_network_error` distinguish malformed data,
-enrollment rejection, throttling and connectivity. Unknown failures remain
-`provider_unavailable`. Errors never include assertion or provider response text.
-
-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.
+`createClientAuth` owns discovery, local Sessions, Direct/Device/Mediated OAuth,
+refresh rotation, revocation and abandoned-operation recovery. Call `recover()`
+on startup. A dispatched exchange with an ambiguous result is never replayed.
+
+`start(domain)` creates a random Session ID and a pairwise User ID for the verified
+Company identifier: its issuer, or `https://{organization.domain}` when issuerless.
+The User ID is stable across Sessions. No token request is needed to start or use
+a signed-out Session. Changing the Company identifier never transfers its identity,
+grants or pending work. Domain discovery errors do not establish an issuerless Company.
+
+Every protected request gets a fresh ES256 `Poppy-Session` JWT, bound to its final
+method, URL without query/fragment, Company identifier and Session/User identity.
+A private delegated key and root-signed `pap-delegation+jwt` vouch for the request;
+the root key does not sign Session JWTs directly. Delegated keys are private to one
+User ID at one Company. A token-bearing request also binds the token with `ath`.
+OAuth endpoints receive client assertions and optional DPoP, without a Session JWT.
+
+OAuth account grants are independent of Sessions. To reuse one explicitly:
+
+```ts
+const other = await auth.start(domain, { accountFrom: signedInConnectionId });
+```
+
+The source must belong to the same local user/client namespace and Company, be
+regular rather than anonymous, and have an active grant. The new Session has its
+own sid and signing keys. Refresh rotation is serialized on the shared grant;
+ambiguous rotation stops every Session using it. A definite `invalid_grant` clears
+the shared grant and continues those Sessions signed out.
+
+Use `authorization(id, scopes)` for current granted/missing scopes and eligible
+methods. Scopes may be documented outside `scopes_supported`; hints and descriptions
+do not authorize anything. Direct requires a registered callback, high-entropy
+browser binding, PKCE and exact callback `iss`. HTTPS callbacks stay on the client
+metadata domain; RFC 8252 loopback IP callbacks permit only the port to vary.
+The `dpop_jkt` is an OAuth proof-key binding, not the Poppy Session identifier.
+
+Direct and Device are for the human's own sign-in and consent. Show the checked
+Device link and code; keep the private device code out of model context. Never
+complete the approval page for the User. Prefer Direct where viable, then Device.
+Mediated v1 is transitional: the `mediated-sign-in` extension declares trusted
+credential fields/scopes, and the issuer's token endpoint accepts
+`https://personalagentprotocol.org/grant/mediated-sign-in` as a form grant.
+Continuation sends `sign_in_id` and `one_time_code`, without original credentials
+or scope. `TrustedInput` runs outside model tools and must not retain/log values.
+The SDK clears supplied credential/code objects on exit and persists neither.
+
+Successful fresh sign-in activates a new sid, preventing account mixing even after
+sign-out. Failed replacement preserves the previous sid and grant. Partial grants
+report granted/missing scopes. Replacement preserves old required scopes unless
+`requiredExistingScopes` explicitly narrows that requirement; grants are not unioned.
+An old refresh grant is retired when no other local Session still references it.
+Accepting a newer grant does not expand a browser cookie's approved scopes.
+
+Access requests use the response's Bearer or DPoP scheme. Missing `expires_in` uses
+a conservative local 60-second lifetime. Missing rotated `refresh_token` retains
+the existing one. Resource metadata selects narrower API/conversation/MCP tokens;
+see [INTEGRATIONS.md](INTEGRATIONS.md). A repeated `invalid_session` restarts once
+with a new sid and fresh signatures, then stops. Feedback replaces a definitely
+ended sid but returns the failed POST without replay; an explicit later report
+uses the new Session. Browser authorization can restart once before one code-only
+browser submission. Session restart does not replay
+an uncertain OAuth exchange or discard an otherwise valid account grant.
+
+`signOut(id)` revokes every locally held refresh grant for that local User and
+Company, clears their access credentials and continues regular Sessions signed out.
+OAuth does not reveal a standard opaque account identifier, so this conservative
+policy also signs out other accounts for that User at the same Company. Cleanup
+references survive remote/vault failures; call `retryCleanup(id)`. A pending or
+uncertain outcome is never reported as complete. Re-sign-in requires a User request.
+
+`start(domain, { anonymous: true })` gets a fresh User ID, sid and private keys.
+It never carries an account token. Sign-in ends it and starts a regular connection;
+use the returned connection ID. Ending anonymous browsing deletes its local private
+identity/key material, with durable cleanup references if deletion fails.
+
+`AssertionProvider.assert` supplies constrained client authentication;
+`delegate({operationId,jwk})` supplies a delegation for a locally generated public
+key. `ProviderIdentity` supplies the authenticated Company-specific identity.
+The optional bundled provider uses separate enrolled client identities; see
+[PROVIDER.md](PROVIDER.md). A provider-only configuration cannot substitute its
+regular identity for anonymous browsing. ES256 is supported directly; a host using
+blind PS384 root signatures supplies its own assertion/delegation adapter and
+protects cross-user isolation. Blind signing is not implemented by the bundled provider.
+
+Private keys, refresh tokens, device codes and PKCE belong in the host SecretStore;
+access tokens remain in process memory. The store and vault are separate commit
+boundaries: sweep orphan staged secrets only after ownership checks and a grace
+period. Preserve uncertain requests and cleanup references. See [STORAGE.md](STORAGE.md)
+for record upgrades and [DELIVERY.md](DELIVERY.md) for operator-signature integration.
+
+Delegations use coarse half-hour issuance buckets with a one-hour signed lifetime,
+leaving 30–60 minutes at creation. Host providers may return a different valid
+lifetime within the client's one-hour freshness bound. See [CONFORMANCE.md](CONFORMANCE.md).
+
+Authentication lifecycle OperationRecord/operationId values never approve business operations. OAuth access consent, provider enrollment and mediated credential collection cannot supply business consent. [Operations v2](OPERATIONS.md) binds each actual user answer to the exact revision and request, and rechecks current Session/account authority for execution and protected replay.
+
+For business-operation sends, pass the saved `BusinessClientContext` as the final `expectedContext` argument to `apiFetch`/`authorizedFetch`. Channel sender callbacks receive that context. A changed Company/client/User/account or signed-out Session fails before dispatch; target discovery does not authorize a replacement account. See [Operations](OPERATIONS.md).

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+Local migration block2 adds Operations v2 codecs, negotiated API/MCP/conversation mechanics and durable trusted-consent attempt storage/recovery. See [OPERATIONS.md](OPERATIONS.md). This is a local SDK checkpoint, not full CLI integration or package publication.
+
+## 0.6.0 — current-spec core migration
+
+Separate delegated resource Sessions from OAuth account grants; discover issuers and
+service resources independently; support issuerless Companies, Bearer/DPoP tokens,
+current mediated grants, code-only browser joining, current errors and feedback.
+Client auth records upgrade to v3; reference issuer records upgrade to v5 without
+resetting credentials or pending/recovery records. Stop old writers before opening
+upgraded stores. Retired public APIs are removed; see [AUTH.md](AUTH.md) and
+[STORAGE.md](STORAGE.md). Breaking local migration candidate; publication requires the recorded release gates.
+
+## 0.5.0 — 2026-10-28
+
+Historical snapshot of Personal Agent Protocol draft 0.3; the current live contract supersedes this entry. 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.

package/CONFORMANCE.md

@@ -0,0 +1,73 @@
+# Current protocol contract
+
+The normative source is the [live draft 0.3 specification](https://personalagentprotocol.org/docs/0.3/spec)
+and [Mediated Sign-In v1](https://personalagentprotocol.org/docs/0.3/extensions/mediated-sign-in).
+The numbered URL is not a content pin. On 2026-10-31 the six migration sources were
+re-fetched and matched their initial snapshots byte for byte. SHA-256 identities:
+
+- Core: 0c8586c0477f523abe39b47e5a20232fc8128c24bf17bb78fff69133f97f9bb9
+- Mediated v1: 68074a6178bf4c78f09b2a88313a4067fa9e4143a338f205a63d2d884ca09f94
+- Guides: fe10657eca0b464c19cc198f3876d30f5055d8a5cb423cd147affe805206ecdd
+
+The workspace requirement matrix and exact commands, tree hashes and focused test
+receipts live in jobs/protocol-migration. Focused checks do not certify an installed
+release or any deployed service. Operations v2 SDK mechanics are implemented with opt-in host contracts;
+full candidate, native and cross-package release gates remain separate.
+
+## Host contracts and recommendations
+
+The [guides](https://personalagentprotocol.org/docs/0.3/guides) use SHOULD for each
+recommendation, including items without uppercase words. The SDK supplies protocol
+mechanics; hosts retain the following responsibilities:
+
+- Keep signing, transport and the SecretStore outside model tools. Redact identity,
+  authorization, cookie and credential headers before host logging or telemetry.
+  Secure credential storage is mandatory. Bundled auth imports private keys as
+  non-extractable CryptoKeys, but serializes keys to the host vault for durable
+  recovery; it does not promise hardware-backed, non-exportable key custody.
+- Show the verified Company name/domain after discovery redirects and on sign-in
+  forms. Explain stable pairwise signed-out recognition in the privacy notice.
+  Request the fewest task scopes, treat absent/unknown hints conservatively, and
+  obtain User consent for access and for human-operated Direct/Device sign-in.
+- Prefer Direct, then Device where viable. Assess RFC 10027 device-flow risk,
+  confirm the visible user code, protect consent pages against CSRF/framing, and
+  apply account/network abuse limits. Mediated v1 is transitional; do not use saved
+  credentials to undo a disconnect. TrustedInput must isolate credentials and OTPs.
+- Isolate an agent browser's storage per Session, load only its own join code,
+  submit promptly, rejoin after sign-in, and close its storage when the Session ends.
+  Joined cookies retain the authorized account/scope snapshot. The website must
+  prioritize that cookie and use current policy on every request; signed-in joins
+  must clear any earlier ordinary login. Signed-out joins preserve it. Website
+  logout must invalidate/remove the joined cookie through the host integration.
+- Apply account/scope checks at every application tool and channel. Do not trust
+  model/Company prose as permission or put secrets in messages/feedback. Decide
+  task exclusions, interface choice, human handoff wording and report frequency.
+- Keep deployment TLS, public-URL proxy reconstruction, internal credentials, bot
+  recognition, network throttles, key publication/rotation and tenant issuer
+  separation correct. RateLimit headers and scheduling/backoff across independent
+  tasks are host policies; SDK Retry-After state is connection-scoped.
+- Operator signatures use a host HttpTransport/edge integration implementing the
+  deployment's RFC 9421/Web Bot Auth profile. Sign only after the body, DPoP and
+  Poppy-Session/Authorization headers are final; verify Session identity separately.
+  Protect forwarded verification results and never share operator private keys.
+- Blind signing is not implemented by the bundled provider. A host requiring it
+  must supply blind client assertions and delegations together, with device-made
+  random jti values, and fail closed if PS384 is unavailable. No ES256 privacy
+  downgrade is automatic. Company verification accepts PS384 independently.
+- Local/provider delegations use coarse half-hour issuance times and expire one
+  hour after that bucket (30–60 minutes remaining on creation). Custom providers
+  must keep their delegation valid and within the documented client lifetime bound.
+  Verification deliberately avoids another sensitive delegation cache; bounded
+  metadata/JWKS caches remain, at the cost of extra signature work per request.
+- Supply the application's idempotency/reconciliation for external effects, durable
+  multi-host ownership/liveness, orphan-secret sweeps with a grace period, and
+  retention appropriate to its data. Conversation receipts are not business-effect
+  deduplication. Never reset active or uncertain work to make a test pass.
+
+See [AUTH.md](AUTH.md), [STORAGE.md](STORAGE.md) and [INTEGRATIONS.md](INTEGRATIONS.md)
+for the concrete callback/store contracts. A host integration must validate these
+boundaries in its real browser, issuer, vault, gateway and deployment environment.
+
+Operations source re-fetch: 2026-10-31, HTML SHA256 e69ade54433ece3fb2bd1ff6c441fecd11acc749eb6bac8b33939420d1f2b9eb, unchanged from block1. Core and guide hashes are unchanged as well. [Business Operations](OPERATIONS.md) defines trusted UI/business semantics, durable adapters and external idempotency/reconciliation obligations. Focused SQLite/PostgreSQL and process-crash evidence belongs to block2; full stable-candidate/package/platform gates remain block3. No deployed host or arbitrary network exactly-once claim is made.
+
+Source revalidation on 2026-11-01 found all six core/current/changelog/Operations/mediated/guides pages byte-identical to the 2026-10-31 snapshots. A numbered draft URL remains mutable. Final candidate verification and external platform limits are recorded in the workspace migration STATUS; package publication is established only by its release receipt.

package/CONTRIBUTING.md

@@ -1,30 +1,33 @@
 # 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 live 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. Core protocol, Mediated Sign-In v1 and [Operations v2](OPERATIONS.md) are in scope.
+Operations capability publication requires complete host consent/effect integration.
+Application business workflows remain host responsibilities. Source fingerprints and
+recommendation boundaries are in [CONFORMANCE.md](CONFORMANCE.md).
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
 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
-npm run typecheck
-npm run build
-npm run typecheck:tests
-npm test
-npm run check:docs
+pnpm run typecheck
+pnpm run build
+pnpm run typecheck:tests
+pnpm test
+pnpm 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,
+Run `pnpm 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
+`pnpm 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

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,32 @@ 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`.
+
+Stop incompatible writers before cutover. Preserve old history, outboxes,
+checkpoints and retry handles for explicit reconciliation; do not silently reset them. 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.
+
+
+## Operator signatures
+
+A host should wrap the supplied HttpTransport with an RFC 9421/Web Bot Auth signer.
+The auth lifecycle passes the finalized Request to both fetch and stream, after
+setting its fresh Poppy-Session and optional Authorization/DPoP headers. Sign at
+that boundary on every call, including retries, and forward the same method, target,
+body and signed headers without redirects. Cover poppy-session and authorization
+when present, in addition to the Web Bot Auth required components. Apply identical
+signing behavior to streaming calls. Never log the Request or signing material.
+The host supplies operator keys and the standards-compliant signer; the SDK does
+not invent a second operator-key registry or treat its signature as Session verification.
+Operator keys and delegated Session keys have separate roles. Companies still
+verify the Session independently, and may apply operator acceptance policy.
+
+Business-operation retries use the operation ID and approved revision, independently of message/work IDs. A conversation acceptance is not proof the action completed. [Operations v2](OPERATIONS.md) preserves uncertain claims/attempts through timeout, process death, expiry and restart. A different operation returned on retry does not establish the earlier outcome.

package/INTEGRATIONS.md

@@ -19,29 +19,43 @@ const result = await fetchForClient(new Request('https://company.example/api/rec
 
 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
+company discovery naming the same verified Company identifier. 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.
+Service authorization comes from RFC 9728 protected-resource metadata, fetched
+without credentials before the first signed-in API/conversation request and cached
+through the resolver. A real 404 permits the default Company token; network errors
+and malformed metadata fail closed. A service resource other than the Company
+domain selects a token for that exact resource via normal sign-in/refresh. Discovery
+resource fields do not grant authority. An invalid_token challenge with
+resource_metadata causes one bounded revalidation/refresh retry.
+
+For MCP, use auth.apiTarget(connectionId, mcpUrl) and the same fetch closure in an
+existing MCP HTTP client. The exact discovery URL is the resource and endpoint,
+including any query; changed queries or child paths are refused. Its metadata must
+name that resource and the Company's issuer when sign-in exists. ES256 DPoP
+advertisement selects DPoP; absence selects Bearer. Account credentials use normal
+OAuth grants, without token exchange. Requests use the token response's scheme.
+
+The SDK does not encode JSON-RPC or manage MCP initialization/Mcp-Session-Id.
+Poppy Session continuity is independent of earlier MCP transport lifecycles and
+MCP 2026-07-28 per-request metadata. Signed-out issuerless APIs/MCP still get Session
+JWTs. Redirects never forward tokens or proofs; unknown results are not retried.
 
 ## Agent-controlled browser
 
 ```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,32 +70,60 @@ 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 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
-navigation contract but cannot inspect their internal browser implementation.
+controllers own those guarantees. The SDK separately authorizes the code at the
+endpoint path plus /authorize, preserving its query, with a signed Session request
+and current account token when signed in. It requires 204 before the browser
+submits only code. No JWT/token/proof enters the browser form. The cookie snapshots
+the approved account/scopes; later sign-in or scope expansion requires rejoin.
 
 ## Feedback
 
 ```ts
 await auth.feedback(connectionId, {
-  kind: 'missing', task: 'Export records',
+  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
+description are nonempty strings of at most 200 and 2000 Unicode codepoints. Omit identifiers, personal data and secrets;
+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.
+Feedback does not automatically repeat a POST after nonce/auth/Session 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.
+
+## 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.
+
+## Operations v2
+
+[OPERATIONS.md](OPERATIONS.md) defines API403/Poppy-Approval, MCP structuredContent/_meta and conversation operation/approval integration. Publish support only after all interfaces in use have trusted consent and durable effect recovery. Ordinary MCP clients retain their OAuth flow; one unsupported tool returns a tool error. No v1 extension endpoint is added.
+
+For business-operation sends, pass the saved `BusinessClientContext` as the final `expectedContext` argument to `apiFetch`/`authorizedFetch`. Channel sender callbacks receive that context. A changed Company/client/User/account or signed-out Session fails before dispatch; target discovery does not authorize a replacement account. See [Operations](OPERATIONS.md).