kestrel.markets/artifacts/protocol/wire.schema.json

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://kestrel.markets/schema/protocol/wire.schema.json",
  "title": "Kestrel platform wire response composites (slice 1)",
  "description": "GENERATED — DO NOT HAND-EDIT. Reflected from src/protocol/wire.ts by scripts/gen-wire-schema.ts (kestrel-2ttz). Slice 1 = response composites only; opaque payload fields reflect permissively. Regenerate with: bun scripts/gen-wire-schema.ts",
  "$comment": "roots: WireOperation, WireOffer, WireMoney, WireProof, WireOfferResponse, WireOperationEvent, WireSettlementMethod, WireHumanAction, WireResumeAffordance, WireSettlementAffordance",
  "definitions": {
    "Record<string,unknown>": {
      "additionalProperties": {},
      "type": "object"
    },
    "Scope": {
      "description": "Authorization scopes (ADR-0003 two-signer rule). Ordered least→most privileged. Treat as extensible: new scopes may be added, so consumers must not exhaustively switch without a default. (Attestation is modeled separately as  {@link  AttestationRole } , not as a Scope.)\n\nThe trailing three are the FLEET/PM-tier scopes (OSS-ADR-0035 / PLAT-ADR-0031 §2), neither wallet- nor per-act human-signable but granted as a whole PM/trader ENVELOPE via the delegation handshake (PLAT-ADR-0031 §1):  - `fleet-evidence:self`    — a trader reads its OWN blotter/journal/mandate/brief    (PLAT-ADR-0026 §5's own-scope `fleet-evidence read`, adopted here by name).  - `fleet-evidence:subtree` — a PM reads every child trader's evidence across its    workspace subtree (the new PM reach; supersedes 0026's own-only term, split into    `:self` == own and `:subtree` == subtree).  - `fleet:write`            — a PM writes the population (hire/assign/allocate/arm on    the paper path; live-arming still suspends to a human per PLAT-ADR-0003). Widening    stays inexpressible in the algebra — a PM cannot mint authority it does not hold.",
      "enum": [
        "data",
        "sim",
        "grade",
        "paper",
        "broker",
        "live",
        "fleet-evidence:self",
        "fleet-evidence:subtree",
        "fleet:write"
      ],
      "type": "string"
    },
    "SseEventType": {
      "enum": [
        "operation.started",
        "operation.progress",
        "operation.artifact",
        "operation.receipt",
        "operation.suspended",
        "operation.resumed",
        "operation.completed",
        "operation.failed"
      ],
      "type": "string"
    },
    "WireHumanAction": {
      "additionalProperties": false,
      "description": "openapi HumanAction — the contextual human path; `url` is DATA, never followed.",
      "properties": {
        "kind": {
          "const": "claim-and-fund",
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "required": {
          "type": "boolean"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "kind",
        "url",
        "required"
      ],
      "type": "object"
    },
    "WireMoney": {
      "additionalProperties": false,
      "description": "openapi Money — a decimal string + asset code (NOT a bare number).",
      "properties": {
        "asset": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "value",
        "asset"
      ],
      "type": "object"
    },
    "WireOffer": {
      "additionalProperties": false,
      "description": "openapi Offer — `amount` is  {@link  WireMoney } ; bound to exactly one Operation.",
      "properties": {
        "amount": {
          "$ref": "#/definitions/WireMoney"
        },
        "budget": {
          "type": "number"
        },
        "ceiling": {
          "type": "number"
        },
        "expiry": {
          "type": "string"
        },
        "intent_hash": {
          "type": "string"
        },
        "nonce": {
          "type": "string"
        },
        "offer_id": {
          "type": "string"
        },
        "operation_id": {
          "type": "string"
        },
        "requires_human": {
          "type": "boolean"
        },
        "scope": {
          "items": {
            "$ref": "#/definitions/Scope"
          },
          "type": "array"
        },
        "signature": {
          "type": "string"
        },
        "terms_digest": {
          "type": "string"
        }
      },
      "required": [
        "offer_id",
        "operation_id",
        "intent_hash",
        "scope",
        "ceiling",
        "amount",
        "terms_digest",
        "expiry",
        "nonce"
      ],
      "type": "object"
    },
    "WireOfferResponse": {
      "additionalProperties": false,
      "description": "openapi OfferResponse — the STRUCTURED 402 body (§\"The 402 Offer\"). Every face surfaces it as DATA; none may silently redirect into a browser checkout.",
      "properties": {
        "human_action": {
          "$ref": "#/definitions/WireHumanAction"
        },
        "offer": {
          "$ref": "#/definitions/WireOffer"
        },
        "operation_id": {
          "type": "string"
        },
        "proof": {
          "anyOf": [
            {
              "$ref": "#/definitions/WireProof"
            },
            {
              "type": "null"
            }
          ]
        },
        "settlement_methods": {
          "items": {
            "$ref": "#/definitions/WireSettlementMethod"
          },
          "type": "array"
        }
      },
      "required": [
        "operation_id",
        "offer",
        "settlement_methods"
      ],
      "type": "object"
    },
    "WireOperation": {
      "additionalProperties": false,
      "description": "openapi Operation. `cursor` is an opaque STRING; `status` (not `state`); the domain artifacts ride as opaque refs, the real payload arrives over SSE.",
      "properties": {
        "artifacts": {
          "items": {},
          "type": "array"
        },
        "checkpoint": {
          "type": "string"
        },
        "continuation": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ]
        },
        "cursor": {
          "type": "string"
        },
        "intent_hash": {
          "type": "string"
        },
        "offer": {
          "anyOf": [
            {
              "$ref": "#/definitions/WireOffer"
            },
            {
              "type": "null"
            }
          ]
        },
        "operation_id": {
          "type": "string"
        },
        "receipts": {
          "items": {},
          "type": "array"
        },
        "status": {
          "$ref": "#/definitions/WireOperationStatus"
        }
      },
      "required": [
        "operation_id",
        "intent_hash",
        "status",
        "cursor"
      ],
      "type": "object"
    },
    "WireOperationEvent": {
      "additionalProperties": false,
      "description": "openapi OperationEvent — the JSON `data:` payload of an SSE frame; `cursor` echoes the SSE `id:`; the opaque domain payload rides in `data`.",
      "properties": {
        "cursor": {
          "type": "string"
        },
        "data": {
          "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E"
        },
        "operation_id": {
          "type": "string"
        },
        "type": {
          "$ref": "#/definitions/SseEventType"
        }
      },
      "required": [
        "cursor",
        "type",
        "operation_id"
      ],
      "type": "object"
    },
    "WireOperationStatus": {
      "enum": [
        "running",
        "completed",
        "suspended",
        "failed"
      ],
      "type": "string"
    },
    "WireProof": {
      "additionalProperties": false,
      "description": "openapi Proof — the free result already earned at the sealed checkpoint.",
      "properties": {
        "artifacts": {
          "items": {},
          "type": "array"
        },
        "intent_hash": {
          "type": "string"
        },
        "operation_id": {
          "type": "string"
        },
        "proof_id": {
          "type": "string"
        },
        "receipts": {
          "items": {},
          "type": "array"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "proof_id",
        "operation_id"
      ],
      "type": "object"
    },
    "WireResumeAffordance": {
      "additionalProperties": false,
      "description": "openapi Operation.resume (ResumeAffordance) — the self-describing next call that drives a NON-TERMINAL Operation forward (bead kestrel-markets-770.14, ADR-0009). It names the SAME canonical `POST /api/simulate` the caller made, re-driving the SAME durable Operation from `cursor` without repeating completed work. `requires_settlement:true` marks the SPEND BOUNDARY (Operation `status:\"suspended\"`): the attached `offer` must be settled before the resume POST. `detail` is the actionable protocol note the platform ships inline.",
      "properties": {
        "cursor": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        },
        "method": {
          "const": "POST",
          "type": "string"
        },
        "operation_id": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "requires_settlement": {
          "type": "boolean"
        }
      },
      "required": [
        "method",
        "path",
        "operation_id",
        "cursor",
        "requires_settlement",
        "detail"
      ],
      "type": "object"
    },
    "WireSettlementAffordance": {
      "additionalProperties": false,
      "description": "openapi SettlementAffordance — the machine-followable SETTLE rail an Offer advertises (bead kestrel-markets-1gr8, PR #334). Embedded in the 402 OfferResponse and, from wave-3, in the suspended `SimOperationResponse` too: the EXACT wired URL an agent POSTs settlement evidence to (`POST /api/operations/{id}/settlement`), the method, the accepted rails, and the `SettlementRequest` body shape. This is \"where to actually pay\" — distinct from the  {@link  WireResumeAffordance }  `resume` (which re-drives `/api/simulate` AFTER the Offer is settled). Optional on the wire: a response minted before the rail was wired carries none, so the CLI degrades to the resume affordance rather than fabricating a URL.",
      "properties": {
        "accepts": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "body_schema": {
          "additionalProperties": false,
          "properties": {
            "evidence": {
              "additionalProperties": false,
              "properties": {
                "provider_payment_id": {
                  "type": "string"
                }
              },
              "required": [
                "provider_payment_id"
              ],
              "type": "object"
            },
            "method": {
              "type": "string"
            },
            "offer_id": {
              "type": "string"
            }
          },
          "required": [
            "offer_id",
            "method",
            "evidence"
          ],
          "type": "object"
        },
        "detail": {
          "type": "string"
        },
        "method": {
          "const": "POST",
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "method",
        "url"
      ],
      "type": "object"
    },
    "WireSettlementMethod": {
      "additionalProperties": false,
      "description": "openapi SettlementMethod — discriminated on `method` (NOT `kind`).",
      "properties": {
        "accepts": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "method": {
          "enum": [
            "stripe-mpp",
            "x402"
          ],
          "type": "string"
        },
        "network": {
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E"
        }
      },
      "required": [
        "method"
      ],
      "type": "object"
    }
  }
}