@compose-market/sdk 0.4.2 → 0.5.0

package/.speakeasy/tests.arazzo.yaml

@@ -0,0 +1,415 @@
+arazzo: 1.0.1
+info:
+  title: Compose SDK Agent-First Workflows
+  summary: E2E workflow contracts for the Compose SDK, inference, x402, and agentic loops.
+  version: 0.5.0
+sourceDescriptions:
+  - name: x402
+    url: ../specs/x402.openapi.yaml
+    type: openapi
+  - name: inference
+    url: ../specs/inference.openapi.yaml
+    type: openapi
+  - name: agentic
+    url: ../specs/agentic.openapi.yaml
+    type: openapi
+x-speakeasy-test-server:
+  baseUrl: "x-env: COMPOSE_API_TEST_URL; https://api.compose.market"
+workflows:
+  - workflowId: model_discovery_select
+    summary: List, search, and fetch provider-specific parameters for a model.
+    inputs:
+      type: object
+      properties:
+        query:
+          type: string
+          examples: ["gpt-4.1-mini"]
+        modality:
+          type: string
+          examples: ["text"]
+        operation:
+          type: string
+          examples: ["chat"]
+    steps:
+      - stepId: list_modalities
+        operationId: $sourceDescriptions.inference.modality_list
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: list_modality_operations
+        operationId: $sourceDescriptions.inference.modality_operations_list
+        parameters:
+          - name: modality
+            in: path
+            value: "$inputs.modality"
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: list_operation_models
+        operationId: $sourceDescriptions.inference.modality_operation_models_list
+        parameters:
+          - name: modality
+            in: path
+            value: "$inputs.modality"
+          - name: operation
+            in: path
+            value: "$inputs.operation"
+          - name: limit
+            in: query
+            value: 5
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: list_curated_models
+        operationId: $sourceDescriptions.inference.models_list
+        successCriteria:
+          - condition: $statusCode == 200
+        outputs:
+          firstModelId: $response.body#/data/0/modelId
+      - stepId: search_models
+        operationId: $sourceDescriptions.inference.models_search
+        requestBody:
+          contentType: application/json
+          payload:
+            q: "$inputs.query"
+            modality: "$inputs.modality"
+            operation: "$inputs.operation"
+            limit: 5
+        successCriteria:
+          - condition: $statusCode == 200
+        outputs:
+          selectedModelId: $response.body#/data/0/modelId
+      - stepId: get_model
+        operationId: $sourceDescriptions.inference.models_get
+        parameters:
+          - name: model
+            in: path
+            value: $steps.search_models.outputs.selectedModelId
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: get_model_params
+        operationId: $sourceDescriptions.inference.models_params_get
+        parameters:
+          - name: model
+            in: path
+            value: $steps.search_models.outputs.selectedModelId
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: compose_key_session_lifecycle
+    summary: Create a wallet-scoped Compose Key session and observe active session state.
+    inputs:
+      type: object
+      properties:
+        userAddress:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_USER_ADDRESS"]
+        chainId:
+          type: integer
+          examples: [43113]
+        budgetLimit:
+          type: string
+          examples: ["1000000"]
+        expiresAt:
+          type: integer
+          examples: [4102444800000]
+    steps:
+      - stepId: create_session_key
+        operationId: $sourceDescriptions.x402.compose_keys_create
+        parameters:
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+        requestBody:
+          contentType: application/json
+          payload:
+            purpose: session
+            budgetLimit: "$inputs.budgetLimit"
+            expiresAt: "$inputs.expiresAt"
+            chainId: "$inputs.chainId"
+            name: arazzo-session
+        successCriteria:
+          - condition: $statusCode == 201
+        outputs:
+          composeKey: $response.body#/token
+          keyId: $response.body#/keyId
+      - stepId: get_active_session
+        operationId: $sourceDescriptions.x402.session_get_active
+        parameters:
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: revoke_session_key
+        operationId: $sourceDescriptions.x402.compose_keys_revoke
+        parameters:
+          - name: keyId
+            in: path
+            value: $steps.create_session_key.outputs.keyId
+          - name: Authorization
+            in: header
+            value: "Bearer $steps.create_session_key.outputs.composeKey"
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: paid_inference_with_compose_key
+    summary: Execute a paid chat completion with a reusable Compose Key.
+    inputs:
+      type: object
+      properties:
+        composeKey:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_COMPOSE_KEY"]
+        userAddress:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_USER_ADDRESS"]
+        chainId:
+          type: integer
+          examples: [43113]
+        model:
+          type: string
+          examples: ["gpt-4.1-mini"]
+    steps:
+      - stepId: chat_completion
+        operationId: $sourceDescriptions.inference.inference_chat_completions_create
+        parameters:
+          - name: Authorization
+            in: header
+            value: "Bearer $inputs.composeKey"
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+        requestBody:
+          contentType: application/json
+          payload:
+            model: "$inputs.model"
+            stream: false
+            messages:
+              - role: user
+                content: "Return exactly: ok"
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: raw_x402_challenge_retry
+    summary: Discover an x402 challenge, create a signed payment payload externally, and retry.
+    inputs:
+      type: object
+      properties:
+        model:
+          type: string
+          examples: ["gpt-4.1-mini"]
+        chainId:
+          type: integer
+          examples: [43113]
+        maxAmountWei:
+          type: string
+          examples: ["1000000"]
+        paymentSignature:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_PAYMENT_SIGNATURE"]
+    steps:
+      - stepId: request_challenge
+        operationId: $sourceDescriptions.inference.inference_chat_completions_create
+        parameters:
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+          - name: x-x402-max-amount-wei
+            in: header
+            value: "$inputs.maxAmountWei"
+        requestBody:
+          contentType: application/json
+          payload:
+            model: "$inputs.model"
+            stream: false
+            messages:
+              - role: user
+                content: "Return exactly: ok"
+        successCriteria:
+          - condition: $statusCode == 402
+        outputs:
+          paymentRequired: $response.header.PAYMENT-REQUIRED
+      - stepId: retry_with_payment
+        operationId: $sourceDescriptions.inference.inference_chat_completions_create
+        parameters:
+          - name: PAYMENT-SIGNATURE
+            in: header
+            value: "$inputs.paymentSignature"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+          - name: x-x402-max-amount-wei
+            in: header
+            value: "$inputs.maxAmountWei"
+        requestBody:
+          contentType: application/json
+          payload:
+            model: "$inputs.model"
+            stream: false
+            messages:
+              - role: user
+                content: "Return exactly: ok"
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: streaming_inference_realtime_frames
+    summary: Stream chat and Responses API frames, including reasoning, tool calls, partial images, receipts, and errors.
+    inputs:
+      type: object
+      properties:
+        composeKey:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_COMPOSE_KEY"]
+        userAddress:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_USER_ADDRESS"]
+        chainId:
+          type: integer
+          examples: [43113]
+        textModel:
+          type: string
+          examples: ["gpt-4.1-mini"]
+        imageModel:
+          type: string
+          examples: ["gpt-image-1"]
+        videoId:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_VIDEO_ID"]
+    steps:
+      - stepId: stream_chat_frames
+        operationId: $sourceDescriptions.inference.inference_chat_completions_create
+        parameters:
+          - name: Authorization
+            in: header
+            value: "Bearer $inputs.composeKey"
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+        requestBody:
+          contentType: application/json
+          payload:
+            model: "$inputs.textModel"
+            stream: true
+            messages:
+              - role: user
+                content: "Think briefly, then return exactly: stream ok"
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.header.Content-Type != "application/json"
+      - stepId: stream_response_frames
+        operationId: $sourceDescriptions.inference.inference_responses_create
+        parameters:
+          - name: Authorization
+            in: header
+            value: "Bearer $inputs.composeKey"
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-chain-id
+            in: header
+            value: "$inputs.chainId"
+        requestBody:
+          contentType: application/json
+          payload:
+            model: "$inputs.textModel"
+            stream: true
+            input: "Return exactly: response stream ok"
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.header.Content-Type != "application/json"
+      - stepId: stream_video_status_frames
+        operationId: $sourceDescriptions.inference.inference_videos_stream
+        parameters:
+          - name: videoId
+            in: path
+            value: "$inputs.videoId"
+          - name: timeoutMs
+            in: query
+            value: 1000
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.header.Content-Type != "application/json"
+  - workflowId: runtime_agent_workflow_loop
+    summary: Run agent and workflow streams against the Compose agentic service.
+    x-speakeasy-test-server:
+      baseUrl: "x-env: COMPOSE_RUNTIME_TEST_URL; https://runtime.compose.market"
+    inputs:
+      type: object
+      properties:
+        composeKey:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_COMPOSE_KEY"]
+        userAddress:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_USER_ADDRESS"]
+        chainId:
+          type: integer
+          examples: [43113]
+        agentWallet:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_AGENT_WALLET"]
+        workflowWallet:
+          type: string
+          examples: ["x-env: COMPOSE_TEST_WORKFLOW_WALLET"]
+        threadId:
+          type: string
+          examples: ["arazzo-thread"]
+    steps:
+      - stepId: stream_agent
+        operationId: $sourceDescriptions.agentic.agents_stream_create
+        parameters:
+          - name: Authorization
+            in: header
+            value: "Bearer $inputs.composeKey"
+          - name: x-session-active
+            in: header
+            value: "true"
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-session-budget-remaining
+            in: header
+            value: "1000000"
+          - name: walletAddress
+            in: path
+            value: "$inputs.agentWallet"
+        requestBody:
+          contentType: application/json
+          payload:
+            message: "Return exactly: agent stream ok"
+            threadId: "$inputs.threadId"
+            userAddress: "$inputs.userAddress"
+        successCriteria:
+          - condition: $statusCode == 200
+      - stepId: stream_workflow
+        operationId: $sourceDescriptions.agentic.workflows_chat_stream
+        parameters:
+          - name: Authorization
+            in: header
+            value: "Bearer $inputs.composeKey"
+          - name: x-session-active
+            in: header
+            value: "true"
+          - name: x-session-user-address
+            in: header
+            value: "$inputs.userAddress"
+          - name: x-session-budget-remaining
+            in: header
+            value: "1000000"
+          - name: walletAddress
+            in: path
+            value: "$inputs.workflowWallet"
+        requestBody:
+          contentType: application/json
+          payload:
+            message: "Run one step and return exactly: workflow stream ok"
+            threadId: "$inputs.threadId"
+            userAddress: "$inputs.userAddress"
+        successCriteria:
+          - condition: $statusCode == 200

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.5.0
+
+Root-cause SDK generation, modality catalog, and local build version-sync pass.
+
+### Highlights
+
+- Added the generated modality surface to the inference contract and package exports:
+  - `@compose-market/sdk/inference/modality` for the generated Speakeasy resource.
+  - `sdk.models.modalities.list()`, `.get(modality)`, `.operations(modality)`, and `.models(modality, operation, filters)` on the orchestration client.
+- Added modality-aware model selection to `sdk.models.search({ operation, ... })` and the Arazzo model discovery workflow.
+- Kept realtime inference SSE in the OpenAPI contract while using Speakeasy envelope responses so receipt/payment/request headers remain typed.
+- Expanded `.speakeasy/tests.arazzo.yaml` for modality discovery and realtime stream coverage, including video SSE.
+- Fixed `scripts/sync-version.mjs` so `package.json` is the single source of truth for root lockfile, OpenAPI specs, Arazzo, Speakeasy generation config, generated package metadata, generated JSR metadata, generated Speakeasy locks, and `src/version.ts`.
+- Added the generated `@compose-market/sdk/inference/modality` subpath export and verified the published package surface resolves from Node.
+
+### Tests
+
+- `npm test` - 52 passing tests.
+- `npm run typecheck`
+- `npm run build`
+- `node --input-type=module -e '...'` import check for `@compose-market/sdk`, `/x402`, `/inference`, `/inference/modality`, and `/agentic`.
+- `npm pack --dry-run --cache /tmp/compose-npm-cache`
+
+---
+
+## 0.4.3
+
+OpenAPI/Arazzo contract freeze plus production payment-safety pass.
+
+### Highlights
+
+- Added canonical Speakeasy-ready contracts:
+  - `/Users/jabyl/Downloads/compose-market/packages/sdk/specs/x402.openapi.yaml` for x402 settlement, Compose Keys, sessions, payments, and facilitator operations.
+  - `/Users/jabyl/Downloads/compose-market/packages/sdk/specs/inference.openapi.yaml` for model discovery, inference, and realtime inference streams.
+  - `/Users/jabyl/Downloads/compose-market/packages/sdk/specs/agentic.openapi.yaml` for agents, workflows, memory, workspace search, tools, MCP, and mesh execution.
+  - `/Users/jabyl/Downloads/compose-market/packages/sdk/.speakeasy/tests.arazzo.yaml` for model discovery, Compose Key session lifecycle, Compose Key inference, raw x402 challenge/retry, streaming inference frames, and runtime agent/workflow loops.
+- Added `.speakeasy/workflow.yaml` and `.speakeasy/gen.yaml` so the SDK repo is ready for Speakeasy generation once the CLI is authenticated.
+- Generated and exported Speakeasy TypeScript clients:
+  - `@compose-market/sdk/x402`, `/x402/keys`, `/x402/session`, and `/x402/payments` for x402 settlement, Compose Keys, session state, payments, and facilitator operations.
+  - `@compose-market/sdk/inference` for model discovery, inference, and realtime streams.
+  - `@compose-market/sdk/agentic` plus `/agentic/agent`, `/agentic/workflow`, `/agentic/memory`, and `/agentic/tools`.
+  - Generated schema and operation types under `/inference/schemas`, `/inference/operations`, `/agentic/schemas`, and `/agentic/operations`.
+- Root `npm run build` now compiles the hand-written orchestration SDK plus both generated clients before publish.
+- Hardened money types: Compose Key atomic amounts are strings end to end; `budgetUsd` is now an exact decimal string and `budgetWei` is a positive integer string.
+- Added explicit inference payment modes:
+  - `auto` uses Compose Key first, then raw x402 challenge/sign/retry when a signer is available.
+  - `composeKey` disables raw x402 fallback.
+  - `x402` suppresses Compose Key auth and uses raw x402.
+- Added provider-agnostic `x402Signer` support on the SDK constructor and per-call options.
+- Added x402 payment payload encoding helpers for `PAYMENT-SIGNATURE`.
+- Fixed the lazy `APIPromise` execution path so `.withResponse()` and `await` share one HTTP request instead of risking duplicate paid calls.
+
+### Tests
+
+- `npm run typecheck`
+- `npm test` — 51 passing tests, including raw x402 negotiation and payment-mode coverage.
+- `npm run build`
+- `speakeasy validate openapi` and `speakeasy lint openapi` pass for both OpenAPI documents.
+- `speakeasy lint arazzo` passes for `.speakeasy/tests.arazzo.yaml`.
+- `speakeasy run -y --skip-upload-spec --skip-testing --output console --target x402` passes and generated `generated/x402`.
+- `speakeasy run -y --skip-upload-spec --skip-testing --output console --target inference` passes and generated `generated/inference`.
+- `speakeasy run -y --skip-upload-spec --skip-testing --output console --target agentic` passes and generated `generated/agentic`.
+
+### Speakeasy generation notes
+
+- Speakeasy's automatic generated Arazzo tests are disabled because the SDK owns hand-authored multi-source Arazzo workflows.
+- `inferSSEOverload` is disabled in Speakeasy generation because Speakeasy currently emits invalid TypeScript overloads for SSE-capable operations that also document receipt headers. The generated clients expose the canonical response union/envelope shape, while the hand-written `ComposeSDK` keeps ergonomic streaming helpers.
+
+---
+
 ## 0.4.0
 
 Runtime streams + unified tool-call broadcasting. Enables web/ to consume agent + workflow SSE through typed resources instead of hand-rolled `parseEventStream` loops.

package/README.md

@@ -5,7 +5,7 @@ Official Compose.Market SDK: Compose Keys, x402 v2 facilitator, 45k+ model catal
 [![npm](https://img.shields.io/npm/v/@compose-market/sdk.svg)](https://www.npmjs.com/package/@compose-market/sdk)
 [![license](https://img.shields.io/npm/l/@compose-market/sdk.svg)](./LICENSE)
 
-Zero runtime dependencies. Works in Node 20+, Bun, Deno, Cloudflare Workers, and modern browsers.
+The default `ComposeSDK` orchestration client uses platform fetch/Web Streams APIs. The generated OpenAPI subpath clients use Speakeasy's Zod-backed runtime validation.
 
 ## Install
 
@@ -31,7 +31,7 @@ const sdk = new ComposeSDK({
 // automatically as `Authorization: Bearer compose-<jwt>`.
 const session = await sdk.keys.create({
   purpose: "session",
-  budgetUsd: 10,
+  budgetUsd: "10",
   durationHours: 24,
 });
 
@@ -57,11 +57,42 @@ console.log("\nTotal tokens:", chatCompletion.usage.total_tokens);
 console.log("Settled:", streamReceipt?.finalAmountWei, "wei", streamReceipt?.txHash);
 ```
 
+## Payment modes
+
+Inference defaults to `paymentMode: "auto"`:
+
+1. If a Compose Key is present, the SDK sends it first for the lowest-latency session path.
+2. If no Compose Key is present, or an existing key is rejected and an x402 signer is configured, the SDK requests the raw x402 challenge and retries once with `PAYMENT-SIGNATURE`.
+3. `paymentMode: "composeKey"` disables x402 fallback.
+4. `paymentMode: "x402"` suppresses Compose Key auth and uses the raw x402 path.
+
+The configured `x402Signer` receives the decoded `PaymentRequired` challenge, request method/path/body, wallet context, chain id, and max amount. It returns either a base64-url `PAYMENT-SIGNATURE` string or a signed x402 `PaymentPayload` object; the SDK encodes objects for the header and retries the request once.
+
 ## Capabilities
 
+### Generated OpenAPI Clients
+
+The published package also exports generated clients for direct, contract-first access:
+
+```ts
+import { ComposeMarket as X402 } from "@compose-market/sdk/x402";
+import { ComposeMarket as Inference } from "@compose-market/sdk/inference";
+import { ComposeMarket as Agentic } from "@compose-market/sdk/agentic";
+```
+
+- `@compose-market/sdk/x402` exposes generated contracts for x402 settlement, reusable Compose Keys, session state, payments, and facilitator operations.
+- `@compose-market/sdk/x402/keys`, `@compose-market/sdk/x402/session`, and `@compose-market/sdk/x402/payments` expose generated payment/session resources directly.
+- `@compose-market/sdk/inference` exposes generated contracts for model discovery, inference, and realtime inference streams.
+- `@compose-market/sdk/inference/modality` exposes the generated modality catalog resource directly.
+- `@compose-market/sdk/agentic` exposes generated contracts for agents, workflows, memory, workspace search, tools, MCP, and mesh execution.
+- `@compose-market/sdk/agentic/agent`, `@compose-market/sdk/agentic/workflow`, `@compose-market/sdk/agentic/memory`, and `@compose-market/sdk/agentic/tools` expose generated agentic resources directly.
+- `@compose-market/sdk/inference/schemas`, `@compose-market/sdk/inference/operations`, `@compose-market/sdk/agentic/schemas`, and `@compose-market/sdk/agentic/operations` expose generated schema and operation types.
+
+The default `ComposeSDK` remains the higher-level orchestration surface: Compose Key first, raw x402 challenge/sign/retry fallback, typed receipts, streaming aggregation, storage, and event bus.
+
 ### Compose Keys
 
-- `sdk.keys.create({ purpose, budgetUsd, durationHours, ... })` — creates a Compose Key JWT. Requires the underlying wallet to have pre-approved USDC to the Compose treasury for the requested budget.
+- `sdk.keys.create({ purpose, budgetUsd, durationHours, ... })` — creates a Compose Key JWT. `budgetUsd` must be a decimal string with at most 6 fractional digits; `budgetWei` must be a positive integer string. Requires the underlying wallet to have pre-approved USDC to the Compose treasury for the requested budget.
 - `sdk.keys.getActive({ chainId? })` — returns current session metadata (budget, expiry, warnings). **Does not** return the token; the token is returned exactly once by `create()` and must be persisted by the integrator.
 - `sdk.keys.list()` — lists all keys for the attached wallet.
 - `sdk.keys.get(keyId)` — inspects a single key. Requires possession of that key's JWT.
@@ -72,9 +103,13 @@ console.log("Settled:", streamReceipt?.finalAmountWei, "wei", streamReceipt?.txH
 
 - `sdk.models.list()` — curated ~612-model set, canonical Compose shape (`{ modelId, name, provider, type, contextWindow, pricing, input, output, ... }`).
 - `sdk.models.listAll()` — full ~45k catalog.
-- `sdk.models.search({ q, modality, provider, priceMaxPerMTok, contextWindowMin, streaming, cursor, limit })` — cursor-paginated search.
+- `sdk.models.search({ q, modality, operation, provider, priceMaxPerMTok, contextWindowMin, streaming, cursor, limit })` — cursor-paginated search.
 - `sdk.models.get(modelId)` — single model details.
 - `sdk.models.getParams(modelId)` — optional per-model parameters for image/video generation.
+- `sdk.models.modalities.list()` — canonical modality catalog derived from `models.json` / the registry source of truth.
+- `sdk.models.modalities.get(modality)` — one modality with operations and pricing unit metadata.
+- `sdk.models.modalities.operations(modality)` — operation catalog for a modality.
+- `sdk.models.modalities.models(modality, operation, { q, provider, streaming, cursor, limit })` — operation-specific model selection without provider naming heuristics.
 
 ### Inference
 
@@ -94,6 +129,7 @@ Every billable call resolves to `{ data, receipt, requestId, response }`. The re
 - `sdk.x402.facilitator.chains()` — full chain metadata (USDC contract, explorer, testnet flag).
 - `sdk.x402.facilitator.verify(body)` / `.settle(body)` — direct facilitator access.
 - `sdk.x402.decodePaymentRequired(headerValue)` / `.decodePaymentResponse(headerValue)` / `.decodeReceipt(headerValue)` — typed base64-url decoders for the three x402 v2 headers.
+- `sdk.x402.encodePaymentSignature(value)` / `encodePaymentSignature(value)` — encode a signed x402 `PaymentPayload` for `PAYMENT-SIGNATURE`.
 
 ### Webhooks
 
@@ -163,7 +199,7 @@ await sdk.inference.chat.completions.create(
 );
 ```
 
-The SDK auto-retries 408 / 409 / 425 / 429 / 5xx responses and transient network errors, honors `Retry-After` from 429 responses, and auto-generates an `X-Idempotency-Key` on mutating calls so retries are safe against the Compose facilitator.
+The SDK auto-retries 408 / 409 / 425 / 429 / 5xx responses and transient network errors, honors `Retry-After` from 429 responses, and forwards caller-provided `X-Idempotency-Key` values on mutating calls.
 
 ## Supported chains (v1.0)
 
@@ -175,12 +211,31 @@ Solana support ships in v1.1. Enumerate live chains with `sdk.x402.facilitator.c
 ## What this SDK is NOT
 
 - Not a wallet. The SDK never prompts for a signature, never creates a smart account, never runs KYC. Identity is whatever you already have.
-- Not a retry-forever loop on payment-required errors. 402 responses are surfaced as typed errors; the caller decides what to do next.
+- Not a retry-forever loop on payment-required errors. With an x402 signer, the SDK performs one challenge/sign/retry cycle; otherwise 402 responses are surfaced as typed errors.
 - Not a Thirdweb/Privy/Clerk/Auth0 adapter. It's transport-agnostic on purpose — integrators bring whatever identity stack they already use.
 
 Not bundled:
 - No wallet client, no identity provider, no auth SDK. Bring the wallet address your stack produced and keep the rest of your infrastructure unchanged.
 
+## Contract generation
+
+The canonical OpenAPI contracts live in `specs/x402.openapi.yaml`, `specs/inference.openapi.yaml`, and `specs/agentic.openapi.yaml`. Speakeasy configuration lives in `.speakeasy/`, including the Arazzo workflow tests for model selection, Compose Key sessions, Compose Key inference, raw x402 challenge/retry, streaming frames, and agentic agent/workflow loops.
+
+Generated clients live under `generated/x402`, `generated/inference`, and `generated/agentic`. The root build compiles the hand-written orchestration client and all generated clients before publish.
+
+Speakeasy generation keeps `text/event-stream` in the contracts and uses envelope responses so payment, receipt, and request headers remain part of the typed generated surface. The ergonomic streaming aggregation helpers live on the default `ComposeSDK` orchestration client.
+
+## Local Version Sync
+
+`package.json` is the only version source of truth. `npm run build`, `npm test`, and `npm run typecheck` run `scripts/sync-version.mjs`, which updates:
+
+- Root `package-lock.json`.
+- `specs/*.openapi.yaml` `info.version`.
+- `.speakeasy/tests.arazzo.yaml` `info.version`.
+- `.speakeasy/gen.yaml` TypeScript generation version.
+- Generated package metadata under `generated/x402`, `generated/inference`, and `generated/agentic`.
+- `src/version.ts`.
+
 ## License
 
 MIT

package/dist/http.d.ts

@@ -89,7 +89,7 @@ export declare class HttpClient {
     private readonly options;
     constructor(options: HttpClientOptions);
     request<T>(config: RequestOptions): APIPromise<T>;
-    private execute;
+    private executeRaw;
     private computeBackoff;
     private encodeBody;
     private parseResponseBody;

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH,MAAM,MAAM,SAAS,GAAG,CACpB,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,WAAW;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC9D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAC7D,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KACjE,CAAC;CACL;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,KAAK,CAAC;IACxC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACjD,4DAA4D;IAC5D,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,yEAAyE;IACzE,YAAY,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IACzD,gCAAgC;IAChC,KAAK,CAAC,OAAO,GAAG,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;IACxH,kCAAkC;IAClC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxD;AAuDD,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG;IACjD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,KAAK,CAAC;CAC3C,GAAG,OAAO,CAyDV;AA6DD,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAEhC,OAAO,EAAE,iBAAiB;IAItC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU,CAAC,CAAC,CAAC;YA4BnC,OAAO;IAkGrB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,UAAU;YAOJ,iBAAiB;YAgBjB,YAAY;CAa7B"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}