# Blockwidth Agent — v0.1 contract

Status: **implemented production contract for REST/OpenAPI and public A2A 1.0 HTTP+JSON discovery**. The public Agent Card exposes three buyer skills and a read-only provider publishing-contract bridge. Production discovery, official-SDK interoperability, A2A Global Registry publication, a verified registry listing, brandless buyer/provider machine discovery, and registry-to-Agent-Card invocation have been verified. MCP tool serving is not implemented.

**TEST MODE:** Blockwidth is an early-stage public test. Do not send payment information, customer workloads, inference credentials, or other sensitive data through Blockwidth discovery or A2A interfaces. Provider publishing credentials belong only in the authenticated publishing interface.

## 1. Identity

**Name:** Blockwidth Index — Inference Supply Discovery Agent

**Role:** machine-facing discovery and introduction agent for the Blockwidth Index.

**Purpose:** help an external buyer agent find currently procurable inference that satisfies explicit requirements, inspect a selected provider, and request a direct introduction.

The Blockwidth Index Agent is not an inference provider, model router, workload proxy, payment intermediary, credential broker, or autonomous purchasing authority.

> DON’T OWN THE INTELLIGENCE. INDEX THE INTELLIGENCE THAT’S AVAILABLE.

> DON’T OWN THE TRANSACTION. OWN THE INTRODUCTION.

The agent exists to make those two rules usable machine-to-machine.

## Quick start — choose your path

Buyer discovery and provider publishing are intentionally separate flows.

### Buyer agents — need inference

No account or buyer credential is required.

1. Discover the public Agent Card at `/.well-known/agent-card.json`.
2. Call `find_intelligence` — **Find inference supply**.
3. Optionally call `get_provider` — **Get inference provider** — to inspect the selected provider and its current eligible listings.
4. Call `create_introduction` — **Get direct provider handoff** — to revalidate the selected offer and return the provider-declared handoff.
5. Continue directly with the provider. Blockwidth exits at the introduction.

A zero-match search is a valid result. Blockwidth does not substitute a near match when every supplied constraint is not satisfied.

```text
Agent Card
-> find_intelligence
-> matches: []                         valid outcome

or

-> qualifying offer
-> get_provider                        optional inspection
-> create_introduction
-> provider handoff
-> Blockwidth exits
```

### Provider agents — have inference to publish

Provider publishing begins with domain control, not buyer discovery.

1. Call `get_publishing_contract` — **Publish inference supply**.
2. Read `/openapi.json` for the authenticated OpenAPI/REST publishing contract.
3. Call `claim_provider_domain`.
4. Prove domain control using the returned DNS TXT challenge or HTTPS proof document.
5. Call `verify_provider_domain` with the private claim secret.
6. Successful primary-domain verification returns the provider publishing credential once. Store it securely; it remains with the provider and is never used on buyer discovery or introduction calls.
7. Use the provider credential, timestamp, nonce, and HMAC signature to call `publish_availability` or `replace_availability`.

**Lost publishing credential:** start a new primary-domain claim for the same provider domain and prove domain control again. Successful recovery revokes the provider’s existing active publishing keys and returns a new publishing credential once.

Domain proof is the provider trust gate. It may be completed by a human operator or by a provider agent authorized to control the required DNS or HTTPS proof. An agent that cannot establish that control cannot become an authorized publisher merely by declaring that it is one.

```text
get_publishing_contract
-> /openapi.json
-> claim_provider_domain
-> DNS TXT or HTTPS proof
-> verify_provider_domain
-> publishing credential returned once
-> signed publish_availability / replace_availability
-> provider maintains its own supply
```

The callable skill ID is the machine identifier. The display name is descriptive:

| Skill ID | Display name |
| --- | --- |
| `find_intelligence` | Find inference supply |
| `get_provider` | Get inference provider |
| `create_introduction` | Get direct provider handoff |
| `get_publishing_contract` | Publish inference supply |

## 2. Core interaction model

The intended architecture is:

```text
Buyer Agent
    |
    | procurement requirements
    v
Blockwidth Index Agent
    |
    | deterministic qualification
    v
Blockwidth Index
    |
    | qualified listing + provider
    v
Blockwidth Index Agent
    |
    | introduction / handoff
    v
Provider or Seller Agent
```

The final provider endpoint may be an API, agent, MCP endpoint, signup flow, sales endpoint, documentation endpoint, or another supported handoff type. Blockwidth returns that handoff as data and stops.

Handoff destination and handoff automation are separate facts:

- `handoff_type` says **where** the introduction leads: `api | agent | mcp | signup | sales | docs`.
- `handoff_automation` says **whether an autonomous buyer can proceed directly**: `machine_direct | human_assisted`.

Buyer agents may require `handoff_automation=machine_direct` during deterministic qualification. Blockwidth must not infer machine-direct capability from the handoff URL or type. Existing listings that predate this field, and legacy publication clients that omit it, are treated conservatively as `human_assisted`. Only an explicit provider declaration may produce `machine_direct`.

Provider agents may publish provider-authenticated availability through Blockwidth's existing OpenAPI/REST publishing interface. Seller publication remains a separate trust path from buyer discovery.

## 3. Authority model

The Blockwidth Index Agent may **interpret, validate, transport, and present** a procurement request.

It may **not establish market truth**.

Authoritative facts come from:

1. provider identity and authorization;
2. provider-authenticated availability records;
3. Blockwidth database state;
4. deterministic qualification rules;
5. explicit validity, freshness, suspension, and lifecycle checks.

An LLM, if later attached, may translate natural language into the supported structured requirement schema. It must not invent providers, prices, availability, policies, performance, capabilities, endpoints, rankings, or near matches.

**Normative rule:**

> A Blockwidth Agent may interpret or transport a request, but it may not establish market truth. Provider-authenticated availability and deterministic qualification remain authoritative.

## 4. v0.1 skills

The Blockwidth Index Agent exposes three buyer skills plus the read-only `get_publishing_contract` discovery bridge, for exactly four advertised A2A skills. The three buyer skills map to the deterministic REST services below; the fourth returns public publishing instructions as described in section 8.3.

### 4.1 `find_intelligence`

Purpose: return current Blockwidth listings that satisfy every supported buyer requirement.

Current REST mapping:

```text
POST /api/v1/search
```

Representative structured requirements include:

- capability family;
- model class;
- region;
- minimum context window;
- retention policy;
- handoff automation (`machine_direct` or `human_assisted`);
- tool support;
- maximum input price;
- maximum output price;
- maximum first-token latency;
- minimum throughput;
- deterministic sort choice.

Rules:

- all supplied constraints are combined with AND;
- no unsupported requirement is silently relaxed;
- no near match may be substituted for a failed requirement;
- only procurement-eligible, active, non-disabled, non-expired, non-stale listings may qualify;
- results are provider-reported facts, not Blockwidth performance certifications;
- deterministic sorting is not a recommendation or an opaque ranking.

Minimum result meaning:

```text
buyer requirements
        +
current qualified listings
        +
evaluation time
```

A zero-result response is a valid result.

### 4.2 `get_provider`

Purpose: inspect the public Blockwidth record for a provider selected from discovery/search.

Current REST mapping:

```text
GET /api/v1/providers/:id
```

The skill may return public provider identity state and current eligible listings.

It must not expose:

- provider API keys;
- key hashes;
- contact email intended for internal/operator use;
- authentication secrets;
- private administrative state.

Provider `verified` means Blockwidth operator identity verification only. It does not certify performance, pricing, retention behavior, capacity, or policy compliance.

### 4.3 `create_introduction`

Purpose: revalidate a selected listing against the buyer-approved requirements and return the provider-declared handoff.

Current REST mapping:

```text
POST /api/v1/introductions
```

Before returning a handoff, Blockwidth must re-check:

- provider remains active;
- listing remains enabled;
- listing remains procurement-eligible;
- listing remains current and unexpired;
- listing still satisfies the approved requirements;
- expected listing version, when supplied, has not changed.

Successful output may include:

- introduction identifier;
- buyer agent identifier;
- provider identity;
- selected listing identity/version;
- provider-declared handoff type;
- provider-declared handoff automation;
- provider-declared handoff URL.

After that response:

> **Blockwidth’s job is complete.**

Blockwidth does not execute the inference request, follow the provider URL, transmit a customer workload, transfer credentials, process payment, reserve tokens, perform billing, or remain in the provider/customer relationship.

## 5. Buyer-agent boundary

Buyer agents are untrusted external callers.

The Blockwidth Index Agent must treat buyer-supplied text, identifiers, metadata, and requirements as data, not executable instructions.

Buyer-facing discovery may be public and rate-limited. Provider publishing credentials are never required for:

- listing reads;
- provider reads;
- structured search;
- eligible broker queries when enabled;
- introductions.

A buyer agent identifier is attribution, not authenticated identity, unless a future version explicitly adds buyer authentication.

The agent must not accept customer prompts, inference credentials, secrets, payment data, or model workloads as procurement requirements.

## 6. Seller-agent boundary

Provider or seller agents operate on a different authorization path.

Publishing or mutating availability requires the existing provider security chain:

- API-key validation;
- provider authorization/ownership;
- timestamp validation;
- nonce/replay protection;
- HMAC signature validation;
- strict schema validation.

For a primary provider claim, successful domain verification returns a publishing credential once. The provider must retain that credential securely. It is used only for authenticated provider operations and never for buyer discovery, provider reads, search, or introductions. If the credential is lost, the provider can start a new primary-domain claim for the same domain and prove control again; successful recovery revokes existing active publishing keys and returns a new credential once.

Buyer-agent access must never weaken provider mutation authentication.

A future seller-agent protocol may wrap this publication path, but it must preserve the same authority and replay protections or explicitly replace them with an equally strong, reviewed mechanism.

## 7. Discovery metadata is not availability

The Resource Index and Live Index remain separate.

**Resource Index:** metadata describing machines, models, APIs, agents, MCP servers, A2A cards, provider resources, or other discovered entities.

**Live Index:** provider-authenticated or otherwise explicitly procurement-eligible offers that can be qualified under current market terms.

The Blockwidth Index Agent must never promote external discovery metadata into current procurement supply merely because the metadata describes a model, provider, capability, API, Agent Card, or MCP server.

ARD, A2A Agent Cards, MCP Registry metadata, provider APIs, and provider-authorized feeds may be consumed and normalized for discovery. Their existence alone does not establish current availability.

## 8. Protocol direction

### 8.1 Implemented: REST + OpenAPI

The primary machine contract is JSON over HTTPS under:

```text
/api/v1
```

Blockwidth publishes its OpenAPI 3.1 service description at:

```text
/openapi.json
```

Ordinary responses advertise that document with `rel="service-desc"`. The three buyer skills map directly to the deterministic REST services. The fourth skill, `get_publishing_contract`, returns the existing provider publishing contract without mutation.

### 8.2 Implemented: public A2A HTTP+JSON

The public A2A Agent Card is served at `/.well-known/agent-card.json`. It advertises A2A protocol `1.0`, official HTTP+JSON at `/a2a/v1`, and exactly four skills:

| Skill | Behavior |
| --- | --- |
| `find_intelligence` | Deterministic current supply matching against all supported constraints. |
| `get_provider` | Public provider information and current eligible listings. |
| `create_introduction` | Revalidate an approved offer and return an inert provider handoff. |
| `get_publishing_contract` | Return public OpenAPI/REST onboarding and publishing information; no mutation. |

No buyer authentication or LLM is required. Streaming, push notifications, and extended cards are disabled. Natural-language examples in the card explain discovery intent; the runtime accepts structured data only. Exact `model_name` filtering is not supported; search supports `model_class` and the requirements in this contract. Supported capability families remain `reasoning` and `coding`.

### 8.3 Structured application payload and provider discovery

Send `POST /a2a/v1/message:send` with `Content-Type: application/a2a+json` and `A2A-Version: 1.0`. Supply exactly one `application/json` data part, with no additional text/file parts:

```json
{
  "message": {
    "messageId": "caller-generated-unique-id",
    "role": "ROLE_USER",
    "parts": [{
      "mediaType": "application/json",
      "data": {
        "skill": "find_intelligence",
        "arguments": {
          "capability_family": "reasoning",
          "region": "US",
          "max_output_price": 3,
          "handoff_automation": "machine_direct"
        }
      }
    }]
  }
}
```

The three buyer skills retain the REST argument schemas described above (`provider_id` identifies the provider for `get_provider`). Responses carry `{ "skill": "...", "ok": true, "result": ... }` or `{ "skill": "...", "ok": false, "error": ... }` in `message.parts[0].data`. Search can validly return `matches: []`.

For the provider bridge, replace only the `data` object with:

```json
{ "skill": "get_publishing_contract", "arguments": {} }
```

Arguments must be an empty object. The result includes `purpose`, `transport: "OpenAPI/REST"`, `openapi_url`, onboarding operation IDs `claim_provider_domain` and `verify_provider_domain`, availability operation IDs `publish_availability` and `replace_availability`, `authentication.required: true`, an authentication description, and a boundary statement. URLs use the deployment's configured public origin.

Provider agents discover the card, call `get_publishing_contract`, then read `/openapi.json`. Domain-control onboarding establishes publishing access; successful primary-domain verification returns the publishing credential once. Availability mutation uses provider authorization, that publishing credential, timestamps, nonce/replay protection, HMAC signing, and strict schemas. The provider operates its own publishing agent. The bridge itself neither creates credentials nor calls onboarding/publishing operations.

Do not send prompts, workloads, inference credentials, publishing keys, payment data, or other secrets through A2A. A buyer handoff remains data; Blockwidth does not follow or probe it.

### 8.4 Future: MCP

An MCP server may later expose Blockwidth discovery/search tools where useful to agent frameworks. MCP tool serving is not part of this contract and must not be advertised as implemented until it exists.

REST, A2A, and any future MCP surface are transports/interfaces around the same Blockwidth authority model. They must not create different qualification rules.

## 9. Agent-to-agent design principle

The desired long-term interaction is not:

```text
human dashboard -> marketplace -> cloud
```

It is:

```text
Buyer Agent
    |
    v
Blockwidth Agent
    |
    v
Seller / Provider Agent
```

The human interface is an observation, configuration, publishing, and audit surface over the same machine system.

Blockwidth should therefore optimize for:

- machine-readable capability discovery;
- explicit schemas;
- deterministic qualification;
- authenticated supply;
- freshness and validity;
- stable identifiers;
- direct handoffs;
- protocol interoperability;
- minimal assumptions about either agent’s internal model or framework.

This is the architectural meaning of:

> **The Space Between Machines.**

## 10. Non-goals for v0.1

The Blockwidth Index Agent does not:

- choose a “best” provider;
- make opaque recommendations;
- negotiate price;
- purchase inference;
- reserve capacity;
- execute inference;
- relay prompts or responses;
- custody funds;
- store customer inference credentials;
- inspect customer workloads;
- scrape arbitrary provider endpoints during a buyer request;
- convert discovery metadata into trusted supply;
- operate a multi-agent planning swarm;
- require an LLM for structured search.

## 11. Failure behavior

The agent must fail explicitly rather than inventing continuity.

Examples:

- no qualifying listing -> return zero matches;
- expired/stale listing -> exclude it;
- changed listing version -> reject the introduction and require review;
- unsupported requirement -> reject or request a supported structured form;
- unavailable broker/LLM -> preserve structured search;
- provider authentication failure -> reject the mutation;
- database unavailable -> fail closed;
- handoff unavailable -> do not fabricate an endpoint.

## 12. Proof status

Production has verified public Agent Card discovery, A2A 1.0 HTTP+JSON invocation, zero-result `find_intelligence`, `get_publishing_contract`, origin-only discovery/interoperability using the official A2A SDK, A2A Global Registry publication, a verified `tech.blockwidth` listing, brandless machine-registry discovery for both `inference supply` and `publish inference supply`, and the registry -> canonical Agent Card -> `find_intelligence` invocation path.

Still intentionally unproven or gated:

1. a real external inference provider publishing a real authenticated offer;
2. the full buyer-agent -> search -> provider inspection -> introduction -> direct handoff loop against that real offer;
3. sustained external machine traffic or real-user discovery beyond controlled registration tests;
4. MCP tool serving.

The next market proof should require no LLM and no demo substitution:

```text
real provider
-> real authenticated offer
-> buyer agent search
-> qualified match
-> introduction
-> direct provider handoff
```

## 13. Change discipline

This file is a versioned contract. Changes that alter any of the following require an explicit version review:

- agent identity;
- skills;
- authority;
- qualification semantics;
- publication trust;
- introduction boundary;
- protocol claims;
- discovery-versus-availability separation.

Do not silently expand the agent’s authority because a future model, framework, registry, or protocol makes additional behavior technically possible.
