402mob-merchant-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.7.0
+
+- Add buyer-signed withdrawal/replacement, optimistic response revisions, immutable history reads and closed-state validation for fresh-work requests. Selection remains separate from payment and freezes the selected version.
+
+- Add scoped, expiring merchant session create/list/revoke helpers; parent credential required and no wallet authority conferred.
+
+- Add optional immutable prepared-offer purchase metadata, public resource fields and a hash-verifying `getOfferTerms` reader. Introduced in 0.7.0.
+
+- Opt-in work agreement templates, private execution recovery and validated merchant event cursors. Introduced in 0.7.0.
+
 ## 0.6.0
 
 - Accept semantically identical inspection-plan property order in proposal responses while rejecting unknown or substituted fields.

package/README.md

@@ -1,9 +1,9 @@
 # 402Mob Merchant SDK
 
-**Version 0.6.0** adds fresh-work proposals and `ProtectedInspectionClient`, plus a seller example for advertising buyer-funded inspections. Use `402mob-merchant-sdk@0.6.0` and check the target server’s `workRequests` and `protectedInspections` capabilities before starting.
+**Version 0.7.0** adds linked work agreements and event reads, immutable offer terms, scoped merchant sessions, and fresh-request withdrawal/replacement with versioned responses. Check the target server’s capabilities before calling new methods. The SDK never signs or spends for you.
 
 
-Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.6.0` for these methods; earlier versions do not include them.
+Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.7.0` for these methods; earlier versions do not include them.
 
 **Version 0.4.0** adds worker profiles and discovery, public buyer requests and newest-first Work Ticket reads. Upgrade from 0.3.1 to use these additions. Check the target server's `/v1/capabilities` first; new worker routes require `workerDiscovery`. See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -42,7 +42,7 @@ If a message signer is locked, stop retries. `enrollWithTransaction` can use a s
 Install from npm:
 
 ```sh
-npm install 402mob-merchant-sdk@0.4.0
+npm install 402mob-merchant-sdk@0.7.0
 ```
 
 Version **0.4.0** retains enrollment, resource resolution and seller Work Ticket methods. Enrollment and credential rotation require standard 65-byte EIP-191 signatures; malformed or compact 64-byte signatures are rejected before submission. See the [npm package](https://www.npmjs.com/package/402mob-merchant-sdk) and [source](https://github.com/gggggggg424242/402mob-merchant-sdk).
@@ -287,7 +287,7 @@ SDK requests reject HTTP redirects and never retry automatically. An interrupted
 These methods are available from version 0.3.0.
 
 
-## Delivery complaints (unreleased source)
+## Delivery complaints (0.5.0)
 
 `createDeliveryDisputeChallenge(operationId, request)` and `submitDeliveryDisputeAction(operationId, {challengeId, challengeToken, signature})` support buyer complaints, original-recipient responses, buyer closure and private reads. These methods require version 0.5.0 or later.
 
@@ -318,7 +318,7 @@ Start with `new ProtectedWorkClient({baseUrl}).getCapabilities()` and stop when
 
 ## Fresh-work requests (0.6.0)
 
-Use `createWorkRequestChallenge` / `completeWorkRequest` to publish a buyer-signed public need with acceptance criteria, then `listWorkRequests` / `getWorkRequest` to read it. A merchant client can `proposeWorkRequest` with its declared accepting capability, fee, proposed deadline and seller-funded test budget, or `declineWorkRequest` with a free preflight reason. One immutable response per merchant is allowed.
+Use `createWorkRequestChallenge` / `completeWorkRequest` to publish a buyer-signed public need with acceptance criteria, then `listWorkRequests` / `getWorkRequest` to read it. A merchant client can `proposeWorkRequest` with its declared accepting capability, fee, proposed deadline and seller-funded test budget, or `declineWorkRequest` with a free preflight reason. One current response per merchant is allowed; explicit revisions in 0.7.0 retain all previous versions.
 
 `createWorkRequestSelectionChallenge` / `selectWorkRequestProposal` require the buyer's separate EIP-191 signature. For direct proposals, the SDK validates the returned `workTicketHandoff`, including its exact input fields and the selected format, payout and proposal note. Add the intended buyer wallet and a new persisted grant idempotency key, then follow the existing Work Ticket grant, quote acceptance and payment flow. Selection creates no ticket or payment and does not track either. The deadline and test budget are declarations, not escrow or wallet spending limits. Inputs and responses are public; never include live payment authorizations or secrets.
 
@@ -333,3 +333,19 @@ The grant input is limited to 32 KiB in canonical JSON; an oversized proposal is
 ### Offer a protected inspection service
 
 Use the free [service recipe](https://evidence.contact/protected-inspection-service.json) and [seller walkthrough](https://evidence.contact/protected-inspections.md#offer-this-service). Publish the reviewed `payment-readiness-inspection` worker profile, then propose an explicit protected inspection against an actual `/v1/work-requests` record. Profile writes replace existing capabilities. Buyer selection returns `protectedWorkHandoff`; it does not authorize payment. This is not a prepared-artifact offer or Payment Link. Require confirmed escrow and retained buyer evidence before work. SDK 0.6.0 includes `examples/protected-inspection-service.ts`; earlier SDK 0.5.0 can advertise/search profiles but lacks fresh-proposal and inspection helpers. No automatic job inbox or notification is provided.
+
+## Unreleased work agreement helpers
+
+Version 0.7.0 adds `getWorkAgreementTemplate`, `createWorkExecutionReadChallenge`, `readWorkExecution`, `readMerchantWorkExecution` and `listWorkEvents`. npm 0.6.0 does not include these methods. See https://evidence.contact/work-agreements.md for HTTP/MCP equivalents and the opt-in direct-settlement boundary. Persist event cursors with pending ticket references, then reread each current ticket; event receipt is not permission to spend.
+
+## Immutable offer terms (0.7.0)
+
+Version 0.7.0 accepts optional `purchaseDecision` on `createOffer` and exports its type. `getOfferTerms(merchantId, offerId)` reads and validates the immutable terms document and hash. These methods are not included in published 0.6.0. See https://evidence.contact/purchase-decisions.md for limits and compatibility. Neither declaration nor hash certifies the artifact or authorizes payment.
+
+## Merchant sessions (0.7.0)
+
+`createMerchantSession`, `listMerchantSessions` and `revokeMerchantSession` manage optional scoped, expiring service credentials with a parent merchant key. They neither sign payments nor delegate further sessions. These helpers are absent from npm 0.6.0. See https://evidence.contact/runtime-controls.md.
+
+## Fresh-work lifecycle (0.7.0)
+
+`createWorkRequestWithdrawalChallenge` and `withdrawWorkRequest` close open, unselected demand with the buyer EOA signature. To replace terms, publish a new request/key with optional `supersedesRequestId`. `reviseWorkRequestResponse(requestId, responseId, {expectedTermsHash, kind, terms})` appends a version to your owned response; `getWorkResponseHistory` reads all versions. Selection freezes the exact hash. No action cancels a ticket or authorizes payment. These helpers and closed-state validation are included in 0.7.0; 0.6.0 lacks them. See https://evidence.contact/work-request-lifecycle.md.

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { type PurchaseDecision, type OfferTerms } from "./purchase-decisions.js";
+export type { PurchaseDecision, OfferTerms } from "./purchase-decisions.js";
+import type { WorkAgreementTemplate, WorkExecutionRead, WorkEventPage } from "./work-agreements.js";
+export type * from "./work-agreements.js";
 export type EvmAddress = `0x${string}`;
 export type EvmSignature = `0x${string}`;
 export type TransactionHash = `0x${string}`;
@@ -183,6 +187,9 @@ export interface CredentialRotationResult {
     };
 }
 interface MerchantOfferBase {
+    purchaseDecision?: PurchaseDecision;
+    offerTermsHash?: string;
+    offerTermsPath?: string;
     id: string;
     merchantId: string;
     seriesId: string;
@@ -210,6 +217,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 interface OfferInputBase {
+    purchaseDecision?: PurchaseDecision;
     title: string;
     description: string;
     priceUSDC: string;
@@ -245,6 +253,9 @@ export interface ArtifactCommitment {
 }
 /** A provider-published, fixed-price resource descriptor. */
 export interface AgentResource {
+    purchaseDecision?: PurchaseDecision;
+    offerTermsHash?: string;
+    offerTermsPath?: string;
     artifact?: ArtifactCommitment;
     share?: string;
     id: string;
@@ -380,6 +391,7 @@ export interface WorkerCapability {
     inputDescription: string;
     resultDescription: string;
     resultContentTypes: ArtifactContentType[];
+    settlementModes?: ("direct_prepayment" | "protected_inspection")[] | undefined;
 }
 /** Full replacement. Discovery flags do not cancel or restrict independently addressed tickets. */
 export interface WorkerProfileInput {
@@ -427,6 +439,7 @@ export interface WorkerDirectoryPage {
 }
 export interface FreshWorkRequestInput extends BuyerRequestInput {
     acceptanceCriteria: string[];
+    supersedesRequestId?: string;
 }
 export interface InspectionPlan {
     version: "buyer-probe-v1";
@@ -444,7 +457,7 @@ export interface FreshWorkProposalInput {
     testPurchaseBudgetUSDC: string;
     testPurchasePayer: "seller" | "buyer";
     note: string;
-    settlementMode?: "protected_inspection";
+    settlementMode?: "direct_prepayment" | "protected_inspection";
     inspection?: InspectionPlan;
 }
 export interface FreshWorkDeclineInput {
@@ -454,12 +467,16 @@ export interface FreshWorkDeclineInput {
 export interface PublicFreshWorkRequest extends Omit<FreshWorkRequestInput, "buyer"> {
     id: string;
     kind: "fresh";
-    state: "open" | "selected" | "expired";
+    state: "open" | "selected" | "expired" | "withdrawn" | "superseded";
+    closedAt?: string;
+    supersededByRequestId?: string;
     createdAt: string;
     expiresAt: string;
     selectedProposalId: string | null;
 }
 export type FreshWorkResponse = {
+    revision?: number;
+    previousTermsHash?: string;
     id: string;
     requestId: string;
     merchantId: string;
@@ -473,6 +490,20 @@ export type FreshWorkResponse = {
     kind: "decline";
     terms: FreshWorkDeclineInput;
 });
+export type FreshWorkResponseRevision = {
+    expectedTermsHash: string;
+} & ({
+    kind: "proposal";
+    terms: FreshWorkProposalInput;
+} | {
+    kind: "decline";
+    terms: FreshWorkDeclineInput;
+});
+export interface FreshWorkResponseHistory {
+    requestId: string;
+    responseId: string;
+    versions: FreshWorkResponse[];
+}
 export interface FreshWorkHandoff {
     kind: "work_ticket_grant";
     method: "POST";
@@ -632,6 +663,21 @@ export declare class MerchantApiError extends Error {
  * Minimal, dependency-free HTTP client for 402Mob agent resource resolution and merchant management.
  * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
  */
+export type MerchantSessionScope = "merchant:manage" | "merchant:sales:read" | "merchant:work";
+export interface MerchantSessionInput {
+    name: string;
+    scopes: MerchantSessionScope[];
+    expiresInSeconds: number;
+}
+export interface MerchantSession {
+    id: string;
+    name: string;
+    scopes: MerchantSessionScope[];
+    createdAt: string;
+    expiresAt: string;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+}
 export declare class MerchantClient {
     #private;
     private readonly baseUrl;
@@ -671,10 +717,20 @@ export declare class MerchantClient {
     getProviderResources(merchantId: string): Promise<AgentProviderCatalog>;
     /** Resolve an older resource ID to its currently published version. This call is public. */
     resolveLatestResource(merchantId: string, offerId: string): Promise<ResolvedAgentResource>;
+    /** Read immutable public decision terms, including for an unpublished exact offer. Verifies the origin-backed SHA-256; not a seller signature. */
+    getOfferTerms(merchantId: string, offerId: string): Promise<OfferTerms>;
     setDiscoverable(discoverable: boolean): Promise<{
         merchantId: string;
         discoverable: boolean;
     }>;
+    createMerchantSession(input: MerchantSessionInput): Promise<{
+        session: MerchantSession;
+        token: string;
+    }>;
+    listMerchantSessions(): Promise<{
+        items: MerchantSession[];
+    }>;
+    revokeMerchantSession(sessionId: string): Promise<MerchantSession>;
     createOffer(input: CreateOfferInput): Promise<MerchantOffer>;
     setOfferActive(offerId: string, active: boolean): Promise<MerchantOffer>;
     listSales(limit?: number): Promise<SaleList>;
@@ -708,6 +764,22 @@ export declare class MerchantClient {
         buyerResultChallenge: string;
         retentionDays: number;
     }>;
+    /** New source API: opt-in linkage; selection still creates neither a ticket nor a payment. */
+    getWorkAgreementTemplate(requestId: string): Promise<WorkAgreementTemplate>;
+    createWorkExecutionReadChallenge(requestId: string, buyer: EvmAddress): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+    }>;
+    readWorkExecution(requestId: string, proof: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<WorkExecutionRead>;
+    readMerchantWorkExecution(requestId: string): Promise<WorkExecutionRead>;
+    listWorkEvents(input?: {
+        after?: number;
+        limit?: number;
+    }): Promise<WorkEventPage>;
     /** Free public demand. Caller persists the key, signs the returned message and completes separately. */
     createWorkRequestChallenge(input: FreshWorkRequestInput, idempotencyKey: string): Promise<BuyerRequestChallenge>;
     completeWorkRequest(input: FreshWorkRequestInput & {
@@ -729,6 +801,24 @@ export declare class MerchantClient {
         response: FreshWorkResponse;
         replay: boolean;
     }>;
+    createWorkRequestWithdrawalChallenge(id: string, input: {
+        buyer: EvmAddress;
+    }): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+    }>;
+    withdrawWorkRequest(id: string, input: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<FreshWorkDetail & {
+        replay: boolean;
+    }>;
+    reviseWorkRequestResponse(id: string, responseId: string, input: FreshWorkResponseRevision): Promise<{
+        response: FreshWorkResponse;
+        replay: boolean;
+    }>;
+    getWorkResponseHistory(id: string, responseId: string): Promise<FreshWorkResponseHistory>;
     createWorkRequestSelectionChallenge(id: string, input: {
         buyer: EvmAddress;
         proposalId: string;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { validPurchaseDecision, decisionCanonical } from "./purchase-decisions.js";
 function requireEip191Signature(signature) {
     if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) {
         throw new TypeError("signature must be a 65-byte EIP-191 signature encoded as 0x-prefixed hex.");
@@ -20,10 +21,11 @@ export class MerchantApiError extends Error {
         this.name = "MerchantApiError";
     }
 }
-/**
- * Minimal, dependency-free HTTP client for 402Mob agent resource resolution and merchant management.
- * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
- */
+function validSession(v) {
+    if (!isRecord(v) || !freshExactKeys(v, ["id", "name", "scopes", "createdAt", "expiresAt", "revokedAt", "lastUsedAt"]) || !uuid(v.id) || !publicText(v.name, 64) || !Array.isArray(v.scopes) || v.scopes.length < 1 || v.scopes.length > 3 || new Set(v.scopes).size !== v.scopes.length || !v.scopes.every(s => ["merchant:manage", "merchant:sales:read", "merchant:work"].includes(String(s))))
+        return false;
+    return [v.createdAt, v.expiresAt].every(x => typeof x === "string" && Number.isFinite(Date.parse(x))) && [v.revokedAt, v.lastUsedAt].every(x => x === null || typeof x === "string" && Number.isFinite(Date.parse(x))) && Date.parse(String(v.expiresAt)) > Date.parse(String(v.createdAt));
+}
 export class MerchantClient {
     baseUrl;
     #apiKey;
@@ -54,7 +56,7 @@ export class MerchantClient {
     }
     /** Full replacement, with separate worker-discovery opt-in. No artifact or wallet action. */
     setWorkerProfile(input) {
-        if (!isWorkerProfileInput(input) || !onlyKeys(input, ["description", "capabilities", "availability", "discoverable"]) || !input.capabilities.every(cap => onlyKeys(cap, ["id", "title", "description", "inputDescription", "resultDescription", "resultContentTypes"])))
+        if (!isWorkerProfileInput(input) || !onlyKeys(input, ["description", "capabilities", "availability", "discoverable"]) || !input.capabilities.every(cap => onlyKeys(cap, ["id", "title", "description", "inputDescription", "resultDescription", "resultContentTypes", "settlementModes"])))
             throw new TypeError("Provide the worker profile PUT body: bounded descriptions, unique capability IDs/formats, availability and explicit discoverable. Unknown or read-only fields are not allowed.");
         const body = normalizedWorkerProfile(input);
         if (new TextEncoder().encode(JSON.stringify(body)).byteLength > 64 * 1024)
@@ -190,9 +192,35 @@ export class MerchantClient {
         }
         return payload;
     }
+    /** Read immutable public decision terms, including for an unpublished exact offer. Verifies the origin-backed SHA-256; not a seller signature. */
+    async getOfferTerms(merchantId, offerId) {
+        const v = await this.request("GET", `/v1/merchants/${checkedWorkTicketId(merchantId)}/offers/${checkedWorkTicketId(offerId)}/terms`);
+        if (!isRecord(v) || Object.keys(v).length !== 14 || !publicText(v.title, 120) || !publicText(v.description, 300) || typeof v.version !== "string" || !/^(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})$/.test(v.version) || v.schema !== "402mob.offer-terms.v1" || v.merchantId !== merchantId || v.offerId !== offerId || !validPurchaseDecision(v.purchaseDecision) || !digest(v.hash) || !address(v.payee) || v.network !== "eip155:8453" || v.asset !== baseUsdc || !atomicAmount(v.amountAtomic) || !["application/json", "text/plain"].includes(v.contentType) || !isRecord(v.artifact) || v.artifact.algorithm !== "sha256-private-proof-v1" || !digest(v.artifact.commitment) || !Number.isSafeInteger(v.artifact.sizeUpperBound) || v.artifact.sizeUpperBound < 1024 || v.artifact.sizeUpperBound > 49152 || v.artifact.sizeUpperBound % 1024)
+            throw invalidPublicResponse();
+        const { hash, ...document } = v;
+        const nodeCryptoModule = "node:crypto";
+        const subtle = globalThis.crypto?.subtle ?? (await import(nodeCryptoModule)).webcrypto.subtle;
+        const bytes = await subtle.digest("SHA-256", new TextEncoder().encode(decisionCanonical(document)));
+        const expected = Array.from(new Uint8Array(bytes), x => x.toString(16).padStart(2, "0")).join("");
+        if (hash !== expected)
+            throw invalidPublicResponse();
+        return v;
+    }
     setDiscoverable(discoverable) {
         return this.request("PUT", "/v1/agent/merchant/discovery", { discoverable }, true);
     }
+    async createMerchantSession(input) {
+        if (!isRecord(input) || Object.keys(input).some(k => !["name", "scopes", "expiresInSeconds"].includes(k)) || !publicText(input.name, 64) || !Array.isArray(input.scopes) || input.scopes.length < 1 || input.scopes.length > 3 || new Set(input.scopes).size !== input.scopes.length || !input.scopes.every(s => ["merchant:manage", "merchant:sales:read", "merchant:work"].includes(s)) || !Number.isInteger(input.expiresInSeconds) || input.expiresInSeconds < 60 || input.expiresInSeconds > 86400)
+            throw new TypeError("Provide a name, distinct merchant scopes and expiry of 60–86400 seconds.");
+        const v = await this.request("POST", "/v1/agent/merchant/sessions", input, true);
+        if (!isRecord(v) || !validSession(v.session) || v.session.name !== input.name.trim() || [...v.session.scopes].sort().join() !== [...input.scopes].sort().join() || Date.parse(v.session.expiresAt) - Date.parse(v.session.createdAt) !== input.expiresInSeconds * 1000 || typeof v.token !== "string" || !/^402mob_session_[A-Za-z0-9_-]{43}$/.test(v.token))
+            throw invalidPublicResponse();
+        return v;
+    }
+    async listMerchantSessions() { const v = await this.request("GET", "/v1/agent/merchant/sessions", undefined, true); if (!isRecord(v) || !Array.isArray(v.items) || v.items.length > 1000 || !v.items.every(validSession) || new Set(v.items.map(x => x.id)).size !== v.items.length)
+        throw invalidPublicResponse(); return v; }
+    async revokeMerchantSession(sessionId) { const v = await this.request("DELETE", `/v1/agent/merchant/sessions/${checkedWorkTicketId(sessionId)}`, undefined, true); if (!validSession(v) || v.id !== sessionId || v.revokedAt === null)
+        throw invalidPublicResponse(); return v; }
     createOffer(input) {
         return this.request("POST", "/v1/agent/merchant/offers", input, true);
     }
@@ -249,6 +277,28 @@ export class MerchantClient {
     submitWorkTicketResult(ticketId, input) {
         return this.request("POST", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}/results`, input, true);
     }
+    /** New source API: opt-in linkage; selection still creates neither a ticket nor a payment. */
+    getWorkAgreementTemplate(requestId) { return this.request("GET", `/v1/work-requests/${checkedWorkTicketId(requestId)}/agreement-template`); }
+    createWorkExecutionReadChallenge(requestId, buyer) { return this.request("POST", `/v1/work-requests/${checkedWorkTicketId(requestId)}/execution-challenges`, { buyer }); }
+    readWorkExecution(requestId, proof) { return this.request("POST", `/v1/work-requests/${checkedWorkTicketId(requestId)}/execution`, { ...proof, signature: requireEip191Signature(proof.signature) }); }
+    readMerchantWorkExecution(requestId) { return this.request("GET", `/v1/agent/work-requests/${checkedWorkTicketId(requestId)}/execution`, undefined, true); }
+    async listWorkEvents(input = {}) {
+        const after = input.after ?? 0, limit = input.limit ?? 50;
+        if (!Number.isSafeInteger(after) || after < 0 || !Number.isInteger(limit) || limit < 1 || limit > 100)
+            throw new TypeError("after must be a nonnegative safe integer; limit must be 1–100.");
+        const page = await this.request("GET", `/v1/agent/work-events?after=${after}&limit=${limit}`, undefined, true);
+        if (!uuid(page.merchantId) || !Array.isArray(page.items) || page.items.length > limit || typeof page.hasMore !== "boolean")
+            throw invalidPublicResponse();
+        let cursor = after;
+        for (const event of page.items) {
+            if (!isRecord(event) || !Number.isSafeInteger(event.sequence) || event.sequence <= cursor || !uuid(event.ticketId) || !workTicketStates.includes(event.state) || !timestamp(event.occurredAt))
+                throw invalidPublicResponse();
+            cursor = event.sequence;
+        }
+        if (page.nextCursor !== cursor || page.hasMore && page.items.length === 0)
+            throw invalidPublicResponse();
+        return page;
+    }
     /** Free public demand. Caller persists the key, signs the returned message and completes separately. */
     createWorkRequestChallenge(input, idempotencyKey) { return this.request("POST", "/v1/work-requests/challenges", input, false, { "Idempotency-Key": idempotencyKey }); }
     completeWorkRequest(input, idempotencyKey) { return this.request("POST", "/v1/work-requests", input, false, { "Idempotency-Key": idempotencyKey }); }
@@ -265,6 +315,10 @@ export class MerchantClient {
     getWorkRequest(id) { return this.request("GET", `/v1/work-requests/${encodeURIComponent(id)}`); }
     proposeWorkRequest(id, input) { return this.request("POST", `/v1/agent/work-requests/${encodeURIComponent(id)}/proposals`, input, true); }
     declineWorkRequest(id, input) { return this.request("POST", `/v1/agent/work-requests/${encodeURIComponent(id)}/declines`, input, true); }
+    createWorkRequestWithdrawalChallenge(id, input) { return this.request("POST", `/v1/work-requests/${encodeURIComponent(id)}/withdrawal-challenges`, input); }
+    withdrawWorkRequest(id, input) { return this.request("POST", `/v1/work-requests/${encodeURIComponent(id)}/withdrawals`, input); }
+    reviseWorkRequestResponse(id, responseId, input) { return this.request("POST", `/v1/agent/work-requests/${encodeURIComponent(id)}/responses/${encodeURIComponent(responseId)}/revisions`, input, true); }
+    getWorkResponseHistory(id, responseId) { return this.request("GET", `/v1/work-requests/${encodeURIComponent(id)}/responses/${encodeURIComponent(responseId)}/history`); }
     createWorkRequestSelectionChallenge(id, input) { return this.request("POST", `/v1/work-requests/${encodeURIComponent(id)}/selection-challenges`, input); }
     selectWorkRequestProposal(id, input) { return this.request("POST", `/v1/work-requests/${encodeURIComponent(id)}/selections`, input); }
     createBuyerRequestChallenge(input, idempotencyKey) {
@@ -363,6 +417,14 @@ export class MerchantClient {
             if (method === "PUT" && JSON.stringify(normalizedWorkerProfile(payload.workerProfile)) !== JSON.stringify(body))
                 throw invalidResponse();
         }
+        if (path.endsWith("/execution-challenges")) {
+            if (!isRecord(body) || !address(body.buyer))
+                throw invalidResponse();
+            const id = path.split("/")[3];
+            const expected = ["402Mob private work execution read", `Origin: ${new URL(this.baseUrl).origin}`, `Request: ${id}`, `Buyer: ${body.buyer.toLowerCase()}`, `Challenge: ${payload.challengeId}`, `Expires: ${payload.expiresAt}`, "Read the linked execution only. This authorizes no grant, payment or result acceptance."].join("\n");
+            if (payload.message !== expected)
+                throw invalidResponse();
+        }
         if ((path.startsWith("/v1/work-requests") || path.startsWith("/v1/agent/work-requests/")) && !isFreshWorkResponse(method, path, payload, body))
             throw invalidResponse();
         if ((path.startsWith("/v1/buyer-requests") || path.startsWith("/v1/agent/buyer-requests/")) && !isBuyerRequestResponse(method, path, payload, body))
@@ -402,14 +464,14 @@ function validWorkerCapabilityId(value) { return typeof value === "string" && /^
 function onlyKeys(value, keys) { return Object.keys(value).every(key => keys.includes(key)); }
 function boundedWorkerText(value, max) { return typeof value === "string" && value.trim().length > 0 && Array.from(value.trim()).length <= max; }
 function normalizedWorkerProfile(value) {
-    return { description: value.description.trim(), capabilities: value.capabilities.map(cap => ({ id: cap.id, title: cap.title.trim(), description: cap.description.trim(), inputDescription: cap.inputDescription.trim(), resultDescription: cap.resultDescription.trim(), resultContentTypes: [...cap.resultContentTypes] })), availability: value.availability, discoverable: value.discoverable };
+    return { description: value.description.trim(), capabilities: value.capabilities.map(cap => ({ id: cap.id, title: cap.title.trim(), description: cap.description.trim(), inputDescription: cap.inputDescription.trim(), resultDescription: cap.resultDescription.trim(), resultContentTypes: [...cap.resultContentTypes], ...(cap.settlementModes ? { settlementModes: [...cap.settlementModes] } : {}) })), availability: value.availability, discoverable: value.discoverable };
 }
 function isWorkerProfileInput(value) {
     if (!isRecord(value) || !boundedWorkerText(value.description, 1000) || (value.availability !== "accepting" && value.availability !== "paused") || typeof value.discoverable !== "boolean" || !Array.isArray(value.capabilities) || !value.capabilities.length || value.capabilities.length > 10)
         return false;
     if (new Set(value.capabilities.map(c => isRecord(c) ? c.id : null)).size !== value.capabilities.length)
         return false;
-    return value.capabilities.every(c => isRecord(c) && validWorkerCapabilityId(c.id) && boundedWorkerText(c.title, 100) && boundedWorkerText(c.description, 1000) && boundedWorkerText(c.inputDescription, 1000) && boundedWorkerText(c.resultDescription, 1000) && Array.isArray(c.resultContentTypes) && c.resultContentTypes.length >= 1 && c.resultContentTypes.length <= 2 && new Set(c.resultContentTypes).size === c.resultContentTypes.length && c.resultContentTypes.every(artifactType));
+    return value.capabilities.every(c => isRecord(c) && validWorkerCapabilityId(c.id) && boundedWorkerText(c.title, 100) && boundedWorkerText(c.description, 1000) && boundedWorkerText(c.inputDescription, 1000) && boundedWorkerText(c.resultDescription, 1000) && Array.isArray(c.resultContentTypes) && c.resultContentTypes.length >= 1 && c.resultContentTypes.length <= 2 && new Set(c.resultContentTypes).size === c.resultContentTypes.length && c.resultContentTypes.every(artifactType) && (c.settlementModes === undefined || Array.isArray(c.settlementModes) && c.settlementModes.length >= 1 && c.settlementModes.length <= 2 && new Set(c.settlementModes).size === c.settlementModes.length && c.settlementModes.every(mode => mode === "direct_prepayment" || mode === "protected_inspection")));
 }
 function isWorkerProfileView(value) {
     if (!isRecord(value) || !isRecord(value.merchant) || !uuid(value.merchant.id) || !publicText(value.merchant.name, 100) || !address(value.merchant.payoutAddress) || !isWorkerProfileInput(value.workerProfile))
@@ -486,7 +548,8 @@ function isAgentResource(value) {
         return false;
     const amountAtomic = value.amountAtomic;
     const amountUSDC = value.amountUSDC;
-    return (value.share === undefined || nonempty(value.share)) &&
+    return (value.purchaseDecision === undefined ? value.offerTermsHash === undefined && value.offerTermsPath === undefined : validPurchaseDecision(value.purchaseDecision) && digest(value.offerTermsHash) && typeof value.offerTermsPath === "string" && value.offerTermsPath.endsWith(`/offers/${value.id}/terms`)) &&
+        (value.share === undefined || nonempty(value.share)) &&
         (value.artifact === undefined || (isRecord(value.artifact) && value.artifact.algorithm === "sha256-private-proof-v1" &&
             typeof value.artifact.commitment === "string" && /^[a-f0-9]{64}$/.test(value.artifact.commitment) &&
             Number.isSafeInteger(value.artifact.sizeUpperBound) && Number(value.artifact.sizeUpperBound) >= 1024 &&
@@ -649,7 +712,21 @@ export { ProtectedWorkClient, ProtectedWorkApiError } from "./protected-work.js"
 function isFreshRequest(v) {
     if (!isRecord(v) || Object.hasOwn(v, "buyer"))
         return false;
-    return uuid(v.id) && v.kind === "fresh" && publicText(v.title, 100) && publicText(v.description, 2000) && usdcAtomic(v.maxPriceUSDC) !== undefined && Number(usdcAtomic(v.maxPriceUSDC)) > 0 && artifactType(v.contentType) && Array.isArray(v.acceptanceCriteria) && v.acceptanceCriteria.length >= 1 && v.acceptanceCriteria.length <= 10 && v.acceptanceCriteria.every(x => publicText(x, 300)) && Number.isInteger(v.expiresInSeconds) && Number(v.expiresInSeconds) >= 60 && Number(v.expiresInSeconds) <= 86400 && timestamp(v.createdAt) && timestamp(v.expiresAt) && ["open", "selected", "expired"].includes(String(v.state)) && (v.state === "selected" ? uuid(v.selectedProposalId) : v.selectedProposalId === null);
+    if (v.supersedesRequestId !== undefined && (!uuid(v.supersedesRequestId) || v.supersedesRequestId === v.id))
+        return false;
+    if (v.state === "withdrawn" || v.state === "superseded") {
+        if (!timestamp(v.closedAt))
+            return false;
+    }
+    else if (v.closedAt !== undefined)
+        return false;
+    if (v.state === "superseded") {
+        if (!uuid(v.supersededByRequestId) || v.supersededByRequestId === v.id)
+            return false;
+    }
+    else if (v.supersededByRequestId !== undefined)
+        return false;
+    return uuid(v.id) && v.kind === "fresh" && publicText(v.title, 100) && publicText(v.description, 2000) && usdcAtomic(v.maxPriceUSDC) !== undefined && Number(usdcAtomic(v.maxPriceUSDC)) > 0 && artifactType(v.contentType) && Array.isArray(v.acceptanceCriteria) && v.acceptanceCriteria.length >= 1 && v.acceptanceCriteria.length <= 10 && v.acceptanceCriteria.every(x => publicText(x, 300)) && Number.isInteger(v.expiresInSeconds) && Number(v.expiresInSeconds) >= 60 && Number(v.expiresInSeconds) <= 86400 && timestamp(v.createdAt) && timestamp(v.expiresAt) && ["open", "selected", "expired", "withdrawn", "superseded"].includes(String(v.state)) && (v.state === "selected" ? uuid(v.selectedProposalId) : v.selectedProposalId === null);
 }
 function isInspectionPlan(v) {
     if (!isRecord(v) || !freshExactKeys(v, ["version", "targetUrl", "method", "paymentRecipient", "maxTestAmountAtomic", "maxPaidAttempts"]) || v.version !== "buyer-probe-v1" || v.method !== "GET" || !address(v.paymentRecipient) || v.maxPaidAttempts !== 1 || typeof v.maxTestAmountAtomic !== "string" || !/^(?:0|[1-9][0-9]{0,5}|1000000)$/.test(v.maxTestAmountAtomic) || typeof v.targetUrl !== "string" || v.targetUrl.length > 2048)
@@ -666,10 +743,12 @@ function sameInspectionPlan(a, b) { return isInspectionPlan(a) && isInspectionPl
 function isFreshProposal(v) {
     if (!isRecord(v) || !uuid(v.id) || !uuid(v.requestId) || !uuid(v.merchantId) || !address(v.payoutAddress) || !digest(v.termsHash) || !timestamp(v.createdAt) || !isRecord(v.terms) || !publicText(v.terms.note, 300))
         return false;
+    if (v.revision === undefined ? v.previousTermsHash !== undefined : !Number.isInteger(v.revision) || Number(v.revision) < 2 || Number(v.revision) > 20 || !digest(v.previousTermsHash) || v.previousTermsHash === v.termsHash)
+        return false;
     const t = v.terms;
     if (v.kind === "decline")
         return ["endpoint_unavailable", "unsupported_payment", "scope_unsupported", "capacity_unavailable", "other"].includes(String(t.reason));
-    return v.kind === "proposal" && typeof t.capability === "string" && /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(t.capability) && publicText(t.deliverable, 300) && usdcAtomic(t.priceUSDC) !== undefined && Number(usdcAtomic(t.priceUSDC)) > 0 && timestamp(t.deliveryDeadline) && usdcAtomic(t.testPurchaseBudgetUSDC) !== undefined && (t.settlementMode === "protected_inspection" ? t.testPurchasePayer === "buyer" && isInspectionPlan(t.inspection) && t.inspection.maxTestAmountAtomic === usdcAtomic(t.testPurchaseBudgetUSDC) : t.settlementMode === undefined && t.inspection === undefined && t.testPurchasePayer === "seller");
+    return v.kind === "proposal" && typeof t.capability === "string" && /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(t.capability) && publicText(t.deliverable, 300) && usdcAtomic(t.priceUSDC) !== undefined && Number(usdcAtomic(t.priceUSDC)) > 0 && timestamp(t.deliveryDeadline) && usdcAtomic(t.testPurchaseBudgetUSDC) !== undefined && (t.settlementMode === "protected_inspection" ? t.testPurchasePayer === "buyer" && isInspectionPlan(t.inspection) && t.inspection.maxTestAmountAtomic === usdcAtomic(t.testPurchaseBudgetUSDC) : (t.settlementMode === undefined || t.settlementMode === "direct_prepayment") && t.inspection === undefined && t.testPurchasePayer === "seller");
 }
 function freshExactKeys(value, keys) {
     return Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k));
@@ -700,13 +779,36 @@ function isFreshDetail(v, id) {
 }
 function isFreshWorkResponse(method, path, v, body) {
     const args = isRecord(body) ? body : {}, id = path.match(/^\/v1\/(?:agent\/)?work-requests\/([^/?]+)/)?.[1];
+    if (path.endsWith("/agreement-template"))
+        return validAgreementTemplate(v, id);
+    if (path.endsWith("/execution-challenges"))
+        return uuid(v.challengeId) && nonempty(v.message) && timestamp(v.expiresAt);
+    if (path.endsWith("/execution"))
+        return validWorkExecution(v, id);
     const challenge = () => uuid(v.challengeId) && nonempty(v.message) && timestamp(v.expiresAt);
     if (path === "/v1/work-requests/challenges")
         return challenge() && timestamp(v.requestExpiresAt) && digest(v.policyHash) && Date.parse(String(v.expiresAt)) <= Date.parse(String(v.requestExpiresAt));
     if (path === "/v1/work-requests" && method === "POST")
-        return isFreshDetail(v) && typeof v.replay === "boolean" && v.request.title === String(args.title).trim() && v.request.description === String(args.description).trim() && v.request.contentType === args.contentType && v.request.expiresInSeconds === args.expiresInSeconds && usdcAtomic(v.request.maxPriceUSDC) === usdcAtomic(args.maxPriceUSDC) && JSON.stringify(v.request.acceptanceCriteria) === JSON.stringify(args.acceptanceCriteria?.map(x => typeof x === 'string' ? x.trim() : x));
+        return isFreshDetail(v) && typeof v.replay === "boolean" && v.request.supersedesRequestId === args.supersedesRequestId && v.request.title === String(args.title).trim() && v.request.description === String(args.description).trim() && v.request.contentType === args.contentType && v.request.expiresInSeconds === args.expiresInSeconds && usdcAtomic(v.request.maxPriceUSDC) === usdcAtomic(args.maxPriceUSDC) && JSON.stringify(v.request.acceptanceCriteria) === JSON.stringify(args.acceptanceCriteria?.map(x => typeof x === 'string' ? x.trim() : x));
     if (path.startsWith("/v1/work-requests?") || path === "/v1/work-requests" && method === "GET")
         return Array.isArray(v.items) && v.items.length <= 50 && v.items.every(isFreshRequest) && (v.nextCursor === null || Number.isSafeInteger(v.nextCursor) && Number(v.nextCursor) >= 0);
+    if (path.endsWith("/withdrawal-challenges"))
+        return challenge();
+    if (path.endsWith("/withdrawals"))
+        return isFreshDetail(v, id) && v.request.state === "withdrawn" && typeof v.replay === "boolean";
+    const responseId = path.match(/\/responses\/([^/]+)\/(?:history|revisions)$/)?.[1];
+    if (path.endsWith("/history")) {
+        if (v.requestId !== id || v.responseId !== responseId || !Array.isArray(v.versions) || v.versions.length < 1 || v.versions.length > 20 || !v.versions.every(isFreshProposal))
+            return false;
+        const versions = v.versions;
+        return versions.every((p, i) => p.id === responseId && p.requestId === id && p.merchantId === versions[0].merchantId && (i === 0 ? p.revision === undefined && p.previousTermsHash === undefined : p.revision === i + 1 && p.previousTermsHash === versions[i - 1].termsHash));
+    }
+    if (path.endsWith("/revisions")) {
+        if (!isFreshProposal(v.response) || v.response.id !== responseId || v.response.requestId !== id || v.response.kind !== args.kind || v.response.previousTermsHash !== args.expectedTermsHash || !isRecord(args.terms) || typeof v.replay !== "boolean")
+            return false;
+        const terms = v.response.terms;
+        return Object.keys(terms).length === Object.keys(args.terms).length && Object.entries(args.terms).every(([k, x]) => k === "inspection" ? sameInspectionPlan(terms[k], x) : ["priceUSDC", "testPurchaseBudgetUSDC"].includes(k) ? usdcAtomic(terms[k]) === usdcAtomic(x) : JSON.stringify(terms[k]) === JSON.stringify(typeof x === 'string' ? x.trim() : x));
+    }
     if (path.endsWith("/selection-challenges"))
         return challenge() && isFreshProposal(v.proposal) && v.proposal.kind === "proposal" && v.proposal.requestId === id && v.proposal.id === args.proposalId;
     if (path.endsWith("/proposals") || path.endsWith("/declines")) {
@@ -718,3 +820,23 @@ function isFreshWorkResponse(method, path, v, body) {
     return isFreshDetail(v, id) && (method === "GET" || v.request.state === "selected" && typeof v.replay === "boolean");
 }
 export { ProtectedInspectionClient, ProtectedInspectionApiError } from "./protected-inspection.js";
+function validAgreementReference(v, id) {
+    return isRecord(v) && freshExactKeys(v, ["protocol", "requestId", "proposalId", "proposalTermsHash", "settlementMode"]) && v.protocol === "402mob.work-agreement.v1" && uuid(v.requestId) && (!id || v.requestId === id) && uuid(v.proposalId) && digest(v.proposalTermsHash) && v.settlementMode === "direct_prepayment";
+}
+function validAgreementTemplate(v, id) {
+    if (!validAgreementReference(v.agreement, id) || !isRecord(v.grant) || !isRecord(v.grant.input) || !validAgreementReference(v.grant.agreement, id) || stableJson(v.agreement) !== stableJson(v.grant.agreement))
+        return false;
+    const g = v.grant, i = g.input;
+    return freshExactKeys(v, ["agreement", "grant", "tracksTicketCreation", "paymentAuthorized", "grantSignatureRequired", "quoteAcceptanceRequired"]) && freshExactKeys(g, ["merchantId", "capability", "input", "maxPriceUSDC", "expiresInSeconds", "agreement"]) && uuid(g.merchantId) && typeof g.capability === "string" && /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(g.capability) && usdcAtomic(g.maxPriceUSDC) !== undefined && BigInt(usdcAtomic(g.maxPriceUSDC)) > 0n && g.expiresInSeconds === 3600 && i.workRequestId === v.agreement.requestId && i.proposalId === v.agreement.proposalId && i.proposalTermsHash === v.agreement.proposalTermsHash && artifactType(i.contentType) && address(i.payoutAddress) && timestamp(i.deliveryDeadline) && publicText(i.deliverable, 300) && i.testPurchasePayer === "seller" && v.tracksTicketCreation === true && v.paymentAuthorized === false && v.grantSignatureRequired === true && v.quoteAcceptanceRequired === true;
+}
+function validWorkExecution(v, id) {
+    if (!freshExactKeys(v, ["agreement", "execution"]))
+        return false;
+    if (v.agreement === null)
+        return v.execution === null;
+    if (!isRecord(v.agreement) || !isRecord(v.execution))
+        return false;
+    const a = v.agreement, e = v.execution;
+    const reference = { protocol: a.protocol, requestId: a.requestId, proposalId: a.proposalId, proposalTermsHash: a.proposalTermsHash, settlementMode: a.settlementMode };
+    return validAgreementReference(reference, id) && uuid(a.ticketId) && uuid(a.merchantId) && address(a.buyer) && address(a.payTo) && atomicAmount(a.amountAtomic) && publicText(a.deliverable, 300) && artifactType(a.contentType) && timestamp(a.deliveryDeadline) && timestamp(a.createdAt) && e.ticketId === a.ticketId && workTicketStates.includes(e.state) && (e.paymentOperationId === null || uuid(e.paymentOperationId)) && (e.paymentState === null || ["executing", "staged", "settling", "pending", "settled", "failed", "expired"].includes(String(e.paymentState))) && ((e.paymentOperationId === null) === (e.paymentState === null)) && typeof e.resultAvailable === "boolean" && (!e.resultAvailable || digest(e.resultHash)) && (e.resultHash === null || digest(e.resultHash)) && (e.buyerVerdict === null || e.buyerVerdict === "accepted" || e.buyerVerdict === "disputed") && e.deliveryDeadline === a.deliveryDeadline && typeof e.deadlinePassed === "boolean" && (e.retentionExpiresAt === null || timestamp(e.retentionExpiresAt));
+}

package/dist/purchase-decisions.d.ts

@@ -0,0 +1,39 @@
+export interface PurchaseDecision {
+    protocol: '402mob.purchase-decision.v1';
+    intendedUse: string;
+    resultSchema: {
+        uri: string;
+        version: string;
+        sha256: string;
+    } | null;
+    coverage: {
+        asOf: string;
+        from?: string;
+        through?: string;
+    };
+    limitations: string[];
+    reuseTerms: string;
+    publicSample?: string;
+}
+export interface OfferTerms {
+    schema: '402mob.offer-terms.v1';
+    merchantId: string;
+    offerId: string;
+    version: string;
+    title: string;
+    description: string;
+    payee: string;
+    network: 'eip155:8453';
+    asset: string;
+    amountAtomic: string;
+    contentType: 'application/json' | 'text/plain';
+    artifact: {
+        algorithm: 'sha256-private-proof-v1';
+        commitment: string;
+        sizeUpperBound: number;
+    };
+    purchaseDecision: PurchaseDecision;
+    hash: string;
+}
+export declare const decisionCanonical: (v: unknown) => string;
+export declare function validPurchaseDecision(v: unknown): v is PurchaseDecision;

package/dist/purchase-decisions.js

@@ -0,0 +1,26 @@
+const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, required, optional = []) => record(v) && required.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => required.includes(k) || optional.includes(k));
+const text = (v, max) => typeof v === 'string' && v.trim() === v && v.length > 0 && Array.from(v).length <= max;
+const date = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(v) && Number.isFinite(Date.parse(v)) && new Date(v).toISOString().slice(0, 19) === v.slice(0, 19);
+export const decisionCanonical = (v) => v === null || typeof v !== 'object' ? JSON.stringify(v) : Array.isArray(v) ? '[' + v.map(decisionCanonical).join(',') + ']' : '{' + Object.keys(v).sort().map(k => JSON.stringify(k) + ':' + decisionCanonical(v[k])).join(',') + '}';
+export function validPurchaseDecision(v) {
+    if (!keys(v, ['protocol', 'intendedUse', 'resultSchema', 'coverage', 'limitations', 'reuseTerms'], ['publicSample']) || v.protocol !== '402mob.purchase-decision.v1' || !text(v.intendedUse, 500) || !text(v.reuseTerms, 3000) || !Array.isArray(v.limitations) || v.limitations.length < 1 || v.limitations.length > 8 || !v.limitations.every(x => text(x, 300)) || Object.hasOwn(v, 'publicSample') && !text(v.publicSample, 1024))
+        return false;
+    if (v.resultSchema !== null) {
+        const r = v.resultSchema;
+        if (!keys(r, ['uri', 'version', 'sha256']) || typeof r.uri !== 'string' || r.uri.length > 2048 || typeof r.version !== 'string' || !/^(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})$/.test(r.version) || typeof r.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(r.sha256))
+            return false;
+        try {
+            const u = new URL(r.uri);
+            if (!r.uri.startsWith('https://') || /[\s#]/u.test(r.uri) || u.protocol !== 'https:' || u.username || u.password || u.hash)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    const c = v.coverage;
+    if (!keys(c, ['asOf'], ['from', 'through']) || !date(c.asOf) || (c.from === undefined) !== (c.through === undefined) || c.from !== undefined && (!date(c.from) || !date(c.through) || Date.parse(c.from) > Date.parse(c.through)))
+        return false;
+    return new TextEncoder().encode(decisionCanonical(v)).length <= 8192;
+}

package/dist/work-agreements.d.ts

@@ -0,0 +1,55 @@
+import type { ArtifactContentType, EvmAddress, FreshWorkHandoff, WorkTicketState } from './index.js';
+export interface WorkAgreementReference {
+    protocol: '402mob.work-agreement.v1';
+    requestId: string;
+    proposalId: string;
+    proposalTermsHash: string;
+    settlementMode: 'direct_prepayment';
+}
+export interface WorkAgreementTemplate {
+    agreement: WorkAgreementReference;
+    grant: FreshWorkHandoff['body'] & {
+        agreement: WorkAgreementReference;
+    };
+    tracksTicketCreation: true;
+    paymentAuthorized: false;
+    grantSignatureRequired: true;
+    quoteAcceptanceRequired: true;
+}
+export interface WorkAgreementRecord extends WorkAgreementReference {
+    ticketId: string;
+    buyer: EvmAddress;
+    merchantId: string;
+    payTo: EvmAddress;
+    amountAtomic: string;
+    deliverable: string;
+    contentType: ArtifactContentType;
+    deliveryDeadline: string;
+    createdAt: string;
+}
+export interface WorkExecutionRead {
+    agreement: WorkAgreementRecord | null;
+    execution: {
+        ticketId: string;
+        state: WorkTicketState;
+        paymentOperationId: string | null;
+        paymentState: 'executing' | 'staged' | 'settling' | 'pending' | 'settled' | 'failed' | 'expired' | null;
+        resultAvailable: boolean;
+        resultHash: string | null;
+        buyerVerdict: 'accepted' | 'disputed' | null;
+        deliveryDeadline: string;
+        deadlinePassed: boolean;
+        retentionExpiresAt: string | null;
+    } | null;
+}
+export interface WorkEventPage {
+    merchantId: string;
+    items: Array<{
+        sequence: number;
+        ticketId: string;
+        state: WorkTicketState;
+        occurredAt: string;
+    }>;
+    nextCursor: number;
+    hasMore: boolean;
+}

package/dist/work-agreements.js

@@ -0,0 +1 @@
+export {};

package/examples/protected-inspection-service.ts

@@ -1,11 +1,11 @@
 import {MerchantClient,type WorkerProfileInput,type FreshWorkProposalInput,type EvmAddress} from '../dist/index.js';
 
-// Source SDK 0.6.0 example. No side effects on import and no signing or payment.
+// Unreleased source SDK example with explicit settlementModes. No side effects on import and no signing or payment.
 export const inspectionCapabilityId='payment-readiness-inspection';
 export const inspectionWorkerProfile:WorkerProfileInput={
  description:'Inspect buyer-signed endpoint observations and verify claimed Base USDC test payments under the protected inspection policy.',
  availability:'accepting',discoverable:true,
- capabilities:[{id:inspectionCapabilityId,title:'Payment-readiness evidence inspection',description:'Classify one bounded buyer probe. Negative and unresolved findings can be valid delivery. No independent HTTP truth or general audit certification.',inputDescription:'Selected protected_inspection proposal, confirmed service-fee escrow and retained buyer-signed observation. The buyer runs and funds any endpoint test.',resultDescription:'inspection-result-v1 JSON: observation, buyerSignature and fixed classification. Passing evidence is subject to escrow review and appeal.',resultContentTypes:['application/json']}]
+ capabilities:[{id:inspectionCapabilityId,title:'Payment-readiness evidence inspection',description:'Classify one bounded buyer probe. Negative and unresolved findings can be valid delivery. No independent HTTP truth or general audit certification.',inputDescription:'Selected protected_inspection proposal, confirmed service-fee escrow and retained buyer-signed observation. The buyer runs and funds any endpoint test.',resultDescription:'inspection-result-v1 JSON: observation, buyerSignature and fixed classification. Passing evidence is subject to escrow review and appeal.',settlementModes:['protected_inspection'],resultContentTypes:['application/json']}]
 };
 
 // Review real capacity and discovery consent first. Profile PUT fully replaces

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "TypeScript client for resolving agent resources and enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {