clawcash-forge 0.1.2__tar.gz

clawcash_forge-0.1.2/.gitignore

@@ -0,0 +1,51 @@
+# dependencies
+node_modules
+.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+coverage
+
+# next.js
+.next/
+out/
+
+# production
+build
+dist
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+!**/.env.example
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+
+# graphify
+graphify-out/
+
+.vscode
+# Python SDK build and test output
+__pycache__/
+.pytest_cache/
+*.egg-info/
+.venv/
+packages/sdk-python/dist/

clawcash_forge-0.1.2/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: clawcash-forge
+Version: 0.1.2
+Summary: Forge telemetry, discovery, and feedback for FastAPI services
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: build>=1; extra == 'test'
+Requires-Dist: cdp-sdk==1.43.0; extra == 'test'
+Requires-Dist: openapi-spec-validator>=0.7; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: x402==2.10.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Forge for FastAPI (0.1.2 preview)
+
+Forge adds agent traffic telemetry, x402 discovery context, and service feedback to an existing FastAPI app. It does not replace your facilitator, verify payments, or settle funds.
+
+The package is named `clawcash-forge`, imported as `forge_sdk`. Install from PyPI:
+
+```sh
+python -m pip install clawcash-forge==0.1.2
+```
+
+## Integrate
+
+Keep your FastAPI routes, lifespan, payment middleware, and facilitator registration as they are. Wrap the **finished app** and export that wrapper to Uvicorn:
+
+```python
+import os
+from fastapi import FastAPI
+from forge_sdk import init_forge
+
+app = FastAPI()
+# Register your existing routes and middleware here.
+# This includes your existing x402 v1/v2 dispatch middleware.
+
+application = init_forge(app, api_key=os.environ["FORGE_API_KEY"])
+```
+
+```sh
+uvicorn server:application
+```
+
+`app` is still your FastAPI object. `application` is the outer ASGI app that Uvicorn serves. Do not serve `server:app`, which bypasses Forge. With Nginx, preserve `payment-required`, `payment-response`, and legacy `x-payment-response` headers. Keep ASGI lifespan enabled. For an ASGI host without lifespan, explicitly `await application.start()` and `await application.close()` in the host's lifecycle.
+
+Create an API key for your service in Forge first. Initialization downloads only that service's registered resource routes. Non-business routes such as health checks are excluded.
+
+## What changes
+
+- On registered x402 routes, captures status, duration, completion, agent type, client, and search query. Query strings, request bodies, and authorization/payment-signature headers are **not** exported wholesale.
+- Adds `agentType`, `agentTypeOther`, `client`, and `search_query` query declarations to those OpenAPI operations. `agentType` and `client` are required in discovery. Runtime parsing remains optional and never rejects a merchant request for missing context. JSON `agent_context` is also accepted when the complete request body fits 3 KB.
+- Appends feedback guidance to the existing main `x-guidance`, preserving merchant text. OpenAPI 3.0 and 3.1 are supported. Local response references are copied before extension. Ambiguous/composed/external response schemas are skipped.
+- Adds a free `GET /feedback` questionnaire and `POST /feedback` submission route on the merchant's own origin. Invalid submissions explain the accepted schema so an agent can retry. The wrapper forwards submissions to Forge.
+- Adds only `feedback_id` to eligible successful JSON objects, and advertises it in their response schema. The ID is a registered short-lived credential linked to the interaction. This preview uses the backend's **pilot feedback policy**, requesting feedback on every eligible response. It does not implement sampled grants.
+- Adds the feedback invitation to the v2 `payment-required` resource description. Recognized Bazaar `queryParams` declarations receive context fields. Unknown/custom Bazaar schema layouts are preserved, not guessed.
+- Reads settlement evidence from v2 `payment-response` and legacy `x-payment-response`. A 2xx status alone is never treated as payment. Network-qualified payer addresses from successful settlement evidence support Forge's global wallet-linked agent identity.
+
+The legacy v1 challenge **body** is preserved byte for byte. Payment offers, recipients, assets, amounts, and opaque custom discovery fields are preserved. There is no monkey-patching of `_x402_mw`, `_settle_v1`, or facilitator functions. Do not describe this SDK as passive observation: the discovery and feedback changes above are intentional.
+
+## Custom settlement paths
+
+If your custom v1 implementation emits a standard settlement response header, Forge can read it automatically. Otherwise report its actual outcome after settlement, inside the request task:
+
+```python
+application.record_settlement(
+    success=result.success,
+    network="eip155:8453",  # or full Solana CAIP-2 network
+    reference=result.transaction,
+    payer=result.payer,
+    protocol_version=1,
+)
+```
+
+Pass amount in base units as a string and asset address if available. Never infer payment from a request signature or HTTP 200. This is SDK-reported evidence, not independent on-chain verification. Custom background tasks outside the request context must not use this method.
+
+## Failure and response behavior
+
+Collector initialization failures warn and retry in the background. The merchant app remains available, but telemetry, schema enrichment, and feedback IDs are unavailable until initialization succeeds. Configuration errors (invalid collector URL, missing key, feedback route collision) raise at construction so they can be fixed before serving.
+
+Telemetry uses a bounded in-memory queue. It is best-effort and may drop events during prolonged outages, overload, shutdown, or worker termination. Each worker owns its own queue. No disk spool is used. `application.diagnostics` reports readiness and drops.
+
+Feedback link registration can add up to 1.5 seconds to eligible JSON responses. On failure the original response is returned. Streaming responses without a bounded Content-Length, responses larger than 64 KB, compressed/signed/cacheable responses, non-object JSON, and objects already containing reserved feedback fields are not modified. Bounded JSON responses may be buffered across chunks. Merchant exceptions and disconnect cancellation propagate normally.
+
+The feedback endpoint is free and unauthenticated at the merchant boundary. Its token and answers are validated by Forge, which applies the existing feedback rules. Use your normal edge rate limits for this public endpoint.
+
+```python
+application = init_forge(
+    app,
+    api_key=os.environ["FORGE_API_KEY"],
+    api_url="https://dev-api.forge.clawca.sh",
+    feedback_path="/feedback",  # choose another path if you already use this route
+    verification=True,  # automatic temporary ownership proof
+    feedback=True,  # false disables feedback route, IDs and invitations
+    discovery=True,  # false leaves the served OpenAPI/discovery unchanged
+    queue_size=1000,
+)
+```
+
+No public origin is inferred from Host or forwarded headers. Feedback URLs are relative to the same merchant origin. Mount the wrapper at your API root. Register all merchant routes and custom OpenAPI generation before wrapping.
+
+## Preview scope
+
+FastAPI/ASGI only, not Flask/WSGI. This version does not implement the Node SDK's sampled feedback grants, or adapters for every merchant-specific discovery schema. It does not fetch an invitation-specific questionnaire via GET token: public GET returns the fixed current form. Base and Solana settlement metadata are supported. Real funds and the client's private legacy compatibility module have not been exercised by tests.
+
+## Build and test
+
+```sh
+python -m pip install -e '.[test]'
+python -m pytest
+python -m build
+```
+
+The x402 integration test additionally requires `x402==2.10.0` and `cdp-sdk==1.43.0`. Test deployments use FastAPI 0.136.0 and Uvicorn 0.44.0, with a mock collector/facilitator and no payment. `contract.json` is copied from the Node SDK's feedback/context definitions to keep the collector contract aligned.
+
+## Automatic ownership verification
+
+Enabled by default. After initialization Forge obtains a temporary proof, adds `X-Forge-Verification` only to configured resource responses (including unpaid 402 responses), and polls the existing ownership API every 10 seconds. The backend makes an unpaid request to the registered public resource to verify control. Nginx must preserve this response header. No payment signature, API key, or expected proof is sent in that verification request.
+
+Proof-bearing responses use `Cache-Control: private, no-store`. The SDK stops attaching the header after verification completes, when the proof expires, on authorization failure, and at shutdown. Already verified services receive no proof header, including after a restart. Existing merchant headers with the same name are preserved. Temporary collector failures do not block merchant requests. Pass `verification=False` to disable the handshake. `application.verification.status` exposes initializing, pending, complete, unavailable, or disabled.

clawcash_forge-0.1.2/README.md

@@ -0,0 +1,106 @@
+# Forge for FastAPI (0.1.2 preview)
+
+Forge adds agent traffic telemetry, x402 discovery context, and service feedback to an existing FastAPI app. It does not replace your facilitator, verify payments, or settle funds.
+
+The package is named `clawcash-forge`, imported as `forge_sdk`. Install from PyPI:
+
+```sh
+python -m pip install clawcash-forge==0.1.2
+```
+
+## Integrate
+
+Keep your FastAPI routes, lifespan, payment middleware, and facilitator registration as they are. Wrap the **finished app** and export that wrapper to Uvicorn:
+
+```python
+import os
+from fastapi import FastAPI
+from forge_sdk import init_forge
+
+app = FastAPI()
+# Register your existing routes and middleware here.
+# This includes your existing x402 v1/v2 dispatch middleware.
+
+application = init_forge(app, api_key=os.environ["FORGE_API_KEY"])
+```
+
+```sh
+uvicorn server:application
+```
+
+`app` is still your FastAPI object. `application` is the outer ASGI app that Uvicorn serves. Do not serve `server:app`, which bypasses Forge. With Nginx, preserve `payment-required`, `payment-response`, and legacy `x-payment-response` headers. Keep ASGI lifespan enabled. For an ASGI host without lifespan, explicitly `await application.start()` and `await application.close()` in the host's lifecycle.
+
+Create an API key for your service in Forge first. Initialization downloads only that service's registered resource routes. Non-business routes such as health checks are excluded.
+
+## What changes
+
+- On registered x402 routes, captures status, duration, completion, agent type, client, and search query. Query strings, request bodies, and authorization/payment-signature headers are **not** exported wholesale.
+- Adds `agentType`, `agentTypeOther`, `client`, and `search_query` query declarations to those OpenAPI operations. `agentType` and `client` are required in discovery. Runtime parsing remains optional and never rejects a merchant request for missing context. JSON `agent_context` is also accepted when the complete request body fits 3 KB.
+- Appends feedback guidance to the existing main `x-guidance`, preserving merchant text. OpenAPI 3.0 and 3.1 are supported. Local response references are copied before extension. Ambiguous/composed/external response schemas are skipped.
+- Adds a free `GET /feedback` questionnaire and `POST /feedback` submission route on the merchant's own origin. Invalid submissions explain the accepted schema so an agent can retry. The wrapper forwards submissions to Forge.
+- Adds only `feedback_id` to eligible successful JSON objects, and advertises it in their response schema. The ID is a registered short-lived credential linked to the interaction. This preview uses the backend's **pilot feedback policy**, requesting feedback on every eligible response. It does not implement sampled grants.
+- Adds the feedback invitation to the v2 `payment-required` resource description. Recognized Bazaar `queryParams` declarations receive context fields. Unknown/custom Bazaar schema layouts are preserved, not guessed.
+- Reads settlement evidence from v2 `payment-response` and legacy `x-payment-response`. A 2xx status alone is never treated as payment. Network-qualified payer addresses from successful settlement evidence support Forge's global wallet-linked agent identity.
+
+The legacy v1 challenge **body** is preserved byte for byte. Payment offers, recipients, assets, amounts, and opaque custom discovery fields are preserved. There is no monkey-patching of `_x402_mw`, `_settle_v1`, or facilitator functions. Do not describe this SDK as passive observation: the discovery and feedback changes above are intentional.
+
+## Custom settlement paths
+
+If your custom v1 implementation emits a standard settlement response header, Forge can read it automatically. Otherwise report its actual outcome after settlement, inside the request task:
+
+```python
+application.record_settlement(
+    success=result.success,
+    network="eip155:8453",  # or full Solana CAIP-2 network
+    reference=result.transaction,
+    payer=result.payer,
+    protocol_version=1,
+)
+```
+
+Pass amount in base units as a string and asset address if available. Never infer payment from a request signature or HTTP 200. This is SDK-reported evidence, not independent on-chain verification. Custom background tasks outside the request context must not use this method.
+
+## Failure and response behavior
+
+Collector initialization failures warn and retry in the background. The merchant app remains available, but telemetry, schema enrichment, and feedback IDs are unavailable until initialization succeeds. Configuration errors (invalid collector URL, missing key, feedback route collision) raise at construction so they can be fixed before serving.
+
+Telemetry uses a bounded in-memory queue. It is best-effort and may drop events during prolonged outages, overload, shutdown, or worker termination. Each worker owns its own queue. No disk spool is used. `application.diagnostics` reports readiness and drops.
+
+Feedback link registration can add up to 1.5 seconds to eligible JSON responses. On failure the original response is returned. Streaming responses without a bounded Content-Length, responses larger than 64 KB, compressed/signed/cacheable responses, non-object JSON, and objects already containing reserved feedback fields are not modified. Bounded JSON responses may be buffered across chunks. Merchant exceptions and disconnect cancellation propagate normally.
+
+The feedback endpoint is free and unauthenticated at the merchant boundary. Its token and answers are validated by Forge, which applies the existing feedback rules. Use your normal edge rate limits for this public endpoint.
+
+```python
+application = init_forge(
+    app,
+    api_key=os.environ["FORGE_API_KEY"],
+    api_url="https://dev-api.forge.clawca.sh",
+    feedback_path="/feedback",  # choose another path if you already use this route
+    verification=True,  # automatic temporary ownership proof
+    feedback=True,  # false disables feedback route, IDs and invitations
+    discovery=True,  # false leaves the served OpenAPI/discovery unchanged
+    queue_size=1000,
+)
+```
+
+No public origin is inferred from Host or forwarded headers. Feedback URLs are relative to the same merchant origin. Mount the wrapper at your API root. Register all merchant routes and custom OpenAPI generation before wrapping.
+
+## Preview scope
+
+FastAPI/ASGI only, not Flask/WSGI. This version does not implement the Node SDK's sampled feedback grants, or adapters for every merchant-specific discovery schema. It does not fetch an invitation-specific questionnaire via GET token: public GET returns the fixed current form. Base and Solana settlement metadata are supported. Real funds and the client's private legacy compatibility module have not been exercised by tests.
+
+## Build and test
+
+```sh
+python -m pip install -e '.[test]'
+python -m pytest
+python -m build
+```
+
+The x402 integration test additionally requires `x402==2.10.0` and `cdp-sdk==1.43.0`. Test deployments use FastAPI 0.136.0 and Uvicorn 0.44.0, with a mock collector/facilitator and no payment. `contract.json` is copied from the Node SDK's feedback/context definitions to keep the collector contract aligned.
+
+## Automatic ownership verification
+
+Enabled by default. After initialization Forge obtains a temporary proof, adds `X-Forge-Verification` only to configured resource responses (including unpaid 402 responses), and polls the existing ownership API every 10 seconds. The backend makes an unpaid request to the registered public resource to verify control. Nginx must preserve this response header. No payment signature, API key, or expected proof is sent in that verification request.
+
+Proof-bearing responses use `Cache-Control: private, no-store`. The SDK stops attaching the header after verification completes, when the proof expires, on authorization failure, and at shutdown. Already verified services receive no proof header, including after a restart. Existing merchant headers with the same name are preserved. Temporary collector failures do not block merchant requests. Pass `verification=False` to disable the handshake. `application.verification.status` exposes initializing, pending, complete, unavailable, or disabled.

clawcash_forge-0.1.2/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clawcash-forge"
+version = "0.1.2"
+description = "Forge telemetry, discovery, and feedback for FastAPI services"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27,<1", "fastapi>=0.115,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "build>=1", "openapi-spec-validator>=0.7", "x402==2.10.0", "cdp-sdk==1.43.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forge_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

clawcash_forge-0.1.2/src/forge_sdk/__init__.py

@@ -0,0 +1,6 @@
+"""Forge for FastAPI. Export the wrapper as the ASGI application."""
+
+from .sdk import Forge, init_forge
+
+__all__ = ["Forge", "init_forge"]
+__version__ = "0.1.2"

clawcash_forge-0.1.2/src/forge_sdk/contract.json

@@ -0,0 +1,169 @@
+{
+  "answersSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "task_outcome": {
+        "type": "string",
+        "enum": [
+          "fully",
+          "partially",
+          "no",
+          "not_evaluated"
+        ]
+      },
+      "improvement": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 1000
+      },
+      "task_summary": {
+        "type": "string",
+        "maxLength": 500,
+        "description": "Optional task summary; omit sensitive details."
+      },
+      "output_quality": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 10,
+        "description": "Optional output usefulness rating: 1 poor, 10 excellent."
+      }
+    },
+    "anyOf": [
+      {
+        "required": [
+          "task_outcome"
+        ]
+      },
+      {
+        "required": [
+          "output_quality"
+        ]
+      },
+      {
+        "required": [
+          "task_summary"
+        ],
+        "properties": {
+          "task_summary": {
+            "pattern": "\\S"
+          }
+        }
+      },
+      {
+        "required": [
+          "improvement"
+        ],
+        "properties": {
+          "improvement": {
+            "pattern": "\\S"
+          }
+        }
+      }
+    ]
+  },
+  "feedbackQuestions": [
+    {
+      "id": "task_summary",
+      "question": "What were you trying to accomplish?",
+      "optional": true,
+      "max_length": 500,
+      "instruction": "Describe the task you used this API for and what you expected from it. If known, include how you found this API, for example 'Found via AgentCash' or 'Called the API directly'. Do not guess the source. Omit sensitive details."
+    },
+    {
+      "id": "output_quality",
+      "question": "How would you rate the output quality?",
+      "optional": true,
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10,
+      "instruction": "Based on your own evaluation of the returned result, rate its usefulness for your task from 1 (poor) to 10 (excellent). Do not infer quality from HTTP success alone. Omit if you have not evaluated it."
+    },
+    {
+      "id": "improvement",
+      "question": "What could be added or improved?",
+      "optional": true,
+      "max_length": 1000,
+      "instruction": "Describe issues you encountered, missing capabilities, or changes that would improve your experience using this API. Distinguish observed problems from suggestions. Omit sensitive details."
+    }
+  ],
+  "discoveryQueryFields": {
+    "agentType": {
+      "type": "string",
+      "enum": [
+        "Codex",
+        "Claude Code",
+        "Hermes",
+        "OpenClaw",
+        "Others (Specify)",
+        "Unknown"
+      ],
+      "description": "Which agent are you running? Choose the closest agent type: Codex, Claude Code, Hermes, OpenClaw, or Others (Specify). For Others, include its name in agentTypeOther. Use Unknown if you cannot identify the agent."
+    },
+    "agentTypeOther": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "Specify the agent name when agentType is Others (Specify)."
+    },
+    "client": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "which x402 client did you use to pay for this [agentcash, pay.sh, coinbase awal (awal), others, unknown]"
+    },
+    "search_query": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "What search query did you use to find this service? Omit if unknown or no search was used."
+    }
+  },
+  "discoveryQueryDescriptions": {
+    "agentType": "Which agent are you running? Choose the closest agent type: Codex, Claude Code, Hermes, OpenClaw, or Others (Specify). For Others, include its name in agentTypeOther. Use Unknown if you cannot identify the agent.",
+    "agentTypeOther": "Specify the agent name when agentType is Others (Specify).",
+    "client": "Which client did you use to access this service? Pick an option [agentcash, awal, pay.sh, others, unknown]",
+    "search_query": "What search query did you use to find this service? Omit if unknown or no search was used."
+  },
+  "discoveryContextSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "agentType",
+      "client"
+    ],
+    "description": "Identify the calling agent and payment client. Use Unknown for an unidentified agent and unknown for an unidentified client. No IDs are needed. These answers are reported claims.",
+    "properties": {
+      "agentType": {
+        "type": "string",
+        "enum": [
+          "Codex",
+          "Claude Code",
+          "Hermes",
+          "OpenClaw",
+          "Others (Specify)",
+          "Unknown"
+        ],
+        "description": "Which agent are you running? Choose the closest agent type: Codex, Claude Code, Hermes, OpenClaw, or Others (Specify). For Others, include its name in agentTypeOther. Use Unknown if you cannot identify the agent."
+      },
+      "agentTypeOther": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "Specify the agent name when agentType is Others (Specify)."
+      },
+      "client": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "Which payment client are you using? [agentcash, awal, pay.sh, others, unknown]"
+      },
+      "discovery_query": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 500,
+        "description": "What search query did you use to find this service? Omit if unknown or no search was used; do not invent a query from your task."
+      }
+    }
+  }
+}

clawcash_forge-0.1.2/src/forge_sdk/schema.py

@@ -0,0 +1,184 @@
+"""Additive OpenAPI/discovery transforms. Never mutate merchant-owned input."""
+
+import copy
+import json
+from importlib.resources import files
+
+CONTRACT = json.loads(files("forge_sdk").joinpath("contract.json").read_text())
+ID_SCHEMA = {"type": "string", "pattern": "^[A-Za-z0-9_-]{22}$"}
+SUBMISSION = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["feedback_id", "answers"],
+    "properties": {"feedback_id": ID_SCHEMA, "answers": CONTRACT["answersSchema"]},
+}
+
+
+def guidance(path, challenge=False):
+    identity = "the returned feedback_id" if challenge else "feedback_id"
+    return (
+        f"After evaluating the result, submit your own quick rating to POST {path} "
+        f"using {identity} to help improve the service. Feedback is free; no payment "
+        "is required."
+    )
+
+
+def append(text, suffix):
+    text = text if isinstance(text, str) else ""
+    return text if suffix in text else (text + "\n\n" + suffix).strip()
+
+
+def resolve(doc, value):
+    """Resolve local references into private copies, with cycle detection."""
+    seen = set()
+    while isinstance(value, dict) and "$ref" in value:
+        ref = value["$ref"]
+        if not isinstance(ref, str) or not ref.startswith("#/") or ref in seen:
+            return None
+        seen.add(ref)
+        target = doc
+        try:
+            for part in ref[2:].split("/"):
+                target = target[part.replace("~1", "/").replace("~0", "~")]
+        except (KeyError, TypeError):
+            return None
+        # Avoid changing semantics of reference siblings.
+        if len(value) != 1:
+            return None
+        value = target
+    return copy.deepcopy(value) if isinstance(value, dict) else None
+
+
+def extend_object(doc, schema, name, field):
+    schema = resolve(doc, schema)
+    if (
+        not schema
+        or schema.get("type") != "object"
+        or any(
+            k in schema
+            for k in ("allOf", "oneOf", "anyOf", "not", "unevaluatedProperties")
+        )
+    ):
+        return None
+    properties = schema.setdefault("properties", {})
+    if name in properties:
+        return None
+    properties[name] = copy.deepcopy(field)
+    return schema
+
+
+def enrich_openapi(document, routes, feedback_path, feedback=True, context=True):
+    doc = copy.deepcopy(document)
+    if not str(doc.get("openapi", "")).startswith(("3.0.", "3.1.")):
+        return doc, set()
+    eligible = set()
+    for route in routes:
+        path, method = route["path"], route["method"].lower()
+        item = doc.get("paths", {}).get(path, {})
+        op = item.get(method) if isinstance(item, dict) else None
+        if not isinstance(op, dict) or "$ref" in op:
+            continue
+        if context:
+            params = op.setdefault("parameters", [])
+            inherited = item.get("parameters", [])
+            known = [resolve(doc, p) for p in params + inherited]
+            fields = (
+                CONTRACT["discoveryQueryFields"]
+                if all(p is not None for p in known)
+                else {}
+            )
+            for name, field in fields.items():
+                if not any(
+                    p.get("name") == name and p.get("in") == "query"
+                    for p in known
+                    if isinstance(p, dict)
+                ):
+                    params.append(
+                        {
+                            "name": name,
+                            "in": "query",
+                            "required": name in ("agentType", "client"),
+                            "schema": copy.deepcopy(field),
+                            "description": CONTRACT["discoveryQueryDescriptions"][name],
+                        }
+                    )
+        if not feedback:
+            continue
+        for status, response in op.get("responses", {}).items():
+            if not str(status).startswith("2"):
+                continue
+            response = resolve(doc, response)
+            media = (
+                response.get("content", {}).get("application/json")
+                if response
+                else None
+            )
+            if not isinstance(media, dict):
+                continue
+            schema = extend_object(doc, media.get("schema"), "feedback_id", ID_SCHEMA)
+            # FastAPI's default JSONResponse has an empty schema.
+            if media.get("schema") == {}:
+                schema = {"type": "object", "properties": {"feedback_id": ID_SCHEMA}}
+            if schema:
+                media["schema"] = schema
+                op["responses"][status] = response
+                eligible.add((route["method"], path, str(status)))
+    if feedback:
+        info = doc.setdefault("info", {})
+        target = info if "x-guidance" in info or "x-guidance" not in doc else doc
+        target["x-guidance"] = append(target.get("x-guidance"), guidance(feedback_path))
+        doc.setdefault("paths", {})[feedback_path] = {
+            "get": {
+                "summary": "Inspect the feedback questionnaire",
+                "security": [],
+                "responses": {
+                    "200": {"description": "Feedback questions and submission schema"}
+                },
+            },
+            "post": {
+                "summary": "Submit service feedback",
+                "security": [],
+                "requestBody": {
+                    "required": True,
+                    "content": {"application/json": {"schema": SUBMISSION}},
+                },
+                "responses": {
+                    "200": {"description": "Feedback accepted"},
+                    "400": {
+                        "description": "Invalid answers. Response includes the expected schema."
+                    },
+                    "503": {"description": "Feedback temporarily unavailable"},
+                },
+            },
+        }
+    return doc, eligible
+
+
+def enrich_challenge(value, path, feedback=True, context=True):
+    result = copy.deepcopy(value)
+    if not isinstance(result, dict) or result.get("x402Version") != 2:
+        return value
+    if feedback and isinstance(result.get("resource"), dict):
+        resource = result["resource"]
+        resource["description"] = append(
+            resource.get("description"), guidance(path, True)
+        )
+    if context:
+        # Extend only a recognized query declaration. Preserve custom schemas.
+        schema = result.get("extensions", {}).get("bazaar", {}).get("schema", {})
+        query = (
+            schema.get("properties", {})
+            .get("input", {})
+            .get("properties", {})
+            .get("queryParams")
+        )
+        if (
+            isinstance(query, dict)
+            and query.get("type") == "object"
+            and "$ref" not in query
+        ):
+            for name, field in CONTRACT["discoveryQueryFields"].items():
+                query.setdefault("properties", {}).setdefault(
+                    name, copy.deepcopy(field)
+                )
+    return result