@openwop/spec-artifacts 2.35.1 → 2.36.0

package/schemas/v2/suspend-request.schema.json

@@ -20,9 +20,10 @@
         "conversation.start",
         "conversation.exchange",
         "conversation.close",
-        "low-confidence"
+        "low-confidence",
+        "credential"
       ],
-      "description": "Discriminator for resume-time routing + UI rendering + observability. Multi-Agent Shift Phase 4 adds `conversation.start` / `conversation.exchange` / `conversation.close` for multi-turn user interjections (see ConversationStartData / ConversationExchangeData / ConversationCloseData below). Phase 1 adds `low-confidence` for the confidence-escalation contract (orchestrator-supervisor suspends below threshold; see LowConfidenceData)."
+      "description": "Discriminator for resume-time routing + UI rendering + observability. Multi-Agent Shift Phase 4 adds `conversation.start` / `conversation.exchange` / `conversation.close` for multi-turn user interjections (see ConversationStartData / ConversationExchangeData / ConversationCloseData below). Phase 1 adds `low-confidence` for the confidence-escalation contract (orchestrator-supervisor suspends below threshold; see LowConfidenceData). RFC 0199 adds `credential` (see CredentialData), gated on `oauth.credentialInterrupt`."
     },
     "key": {
       "type": "string",
@@ -41,7 +42,8 @@
       "description": "Optional auto-reject after this duration. Engine throws InterruptTimeoutError when exceeded."
     },
     "data": {
-      "oneOf": [
+      "description": "Discriminated payload data. The union below lists every per-kind shape; the root `allOf` binds each `kind` to exactly one of them (`interrupt.md` §Per-kind payloads). `anyOf`, not `oneOf`: the shapes are not mutually exclusive by content — a minimal `conversation.start` and `conversation.close` payload are both `{ conversationId }` — so `kind`, not the data, is the discriminator. Before 2.36.0 this was an unbound `oneOf`, which rejected those two minimal payloads and accepted a payload whose `data` matched a different kind's shape (COMPATIBILITY.md §3, 2026-09-22).",
+      "anyOf": [
         {
           "$ref": "#/$defs/ApprovalData"
         },
@@ -65,11 +67,208 @@
         },
         {
           "$ref": "#/$defs/LowConfidenceData"
+        },
+        {
+          "$ref": "#/$defs/CredentialData"
         }
       ]
     }
   },
   "additionalProperties": false,
+  "$comment": "Binds `data` to `kind`: one if/then per kind, so every kind accepts exactly its own per-kind shape and a payload whose `data` belongs to another kind fails.",
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "approval"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ApprovalData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "clarification"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ClarificationData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "external-event"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ExternalEventData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "custom"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/CustomData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "conversation.start"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ConversationStartData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "conversation.exchange"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ConversationExchangeData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "conversation.close"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/ConversationCloseData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "low-confidence"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/LowConfidenceData"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "credential"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "required": [
+          "resumeSchema"
+        ],
+        "properties": {
+          "data": {
+            "$ref": "#/$defs/CredentialData"
+          },
+          "resumeSchema": {
+            "const": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "outcome"
+              ],
+              "properties": {
+                "outcome": {
+                  "enum": [
+                    "authorized",
+                    "declined"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
   "$defs": {
     "ApprovalData": {
       "type": "object",
@@ -95,7 +294,11 @@
         },
         "onTimeout": {
           "type": "string",
-          "enum": ["reject", "approve", "escalate"],
+          "enum": [
+            "reject",
+            "approve",
+            "escalate"
+          ],
           "description": "RFC 0186 §A.3 — the disposition applied when `timeoutMs` elapses with no resolution. Every gate with a timer needs one; two production hosts recorded it as a bare key on `approval.requested` (280 rows on one) because the seat did not exist. `escalate` pairs with a host-defined escalation target. A `timeoutMs` of `0` means no timer, and `onTimeout` is then meaningless."
         },
         "description": {
@@ -369,7 +572,49 @@
         }
       },
       "additionalProperties": false
+    },
+    "CredentialData": {
+      "type": "object",
+      "description": "Payload for kind='credential' (RFC 0199 §C.3). Closed: it names the provider, scopes and reason and carries the host-owned `connectUrl`; it NEVER carries credential material, the interrupt's token, or any value that resolves the interrupt. Gated on `oauth.credentialInterrupt`.",
+      "required": [
+        "provider",
+        "scopes",
+        "reason",
+        "connectUrl"
+      ],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "description": "An advertised `oauth.providers[].id`."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "reason": {
+          "enum": [
+            "missing",
+            "expired",
+            "insufficient_scope"
+          ]
+        },
+        "connectUrl": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://",
+          "description": "Host-owned https URL on the host's own origin that begins the authorization-code grant for the interrupt's initiating Subject. MUST NOT be pre-authenticated and MUST NOT embed the interrupt token."
+        },
+        "credentialRef": {
+          "$ref": "credential-reference.schema.json",
+          "description": "The reference being re-authorized; never material."
+        }
+      },
+      "additionalProperties": false
     }
-  },
-  "x-openwop-seeded-from": "v1"
+  }
 }

package/schemas/v2/tool-descriptor.schema.json

@@ -45,6 +45,31 @@
       "description": "MAY — JSON Schema for the tool's result.",
       "additionalProperties": true
     },
+    "annotations": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "readOnlyHint",
+        "destructiveHint",
+        "idempotentHint",
+        "openWorldHint"
+      ],
+      "description": "RFC 0204. Projection onto MCP ToolAnnotations (2026-07-28), computed from this descriptor's host-assigned safetyTier / replayPolicy / egress by the table in spec/v2/core/tool-catalog.md — never copied from an MCP server's annotations (untrusted upstream) and never left to MCP defaults. All four REQUIRED when present; `annotations.title` is not emitted (`title` is the display name).",
+      "properties": {
+        "readOnlyHint": {
+          "type": "boolean"
+        },
+        "destructiveHint": {
+          "type": "boolean"
+        },
+        "idempotentHint": {
+          "type": "boolean"
+        },
+        "openWorldHint": {
+          "type": "boolean"
+        }
+      }
+    },
     "auth": {
       "type": "object",
       "additionalProperties": false,
@@ -144,7 +169,226 @@
           "source"
         ]
       }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): readOnlyHint is true iff safetyTier is pure or read.",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "properties": {
+          "safetyTier": {
+            "enum": [
+              "pure",
+              "read"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "readOnlyHint": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): readOnlyHint is false for write and exec.",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "properties": {
+          "safetyTier": {
+            "enum": [
+              "write",
+              "exec"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "readOnlyHint": {
+                "const": false
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): destructiveHint is true iff safetyTier is write or exec (safetyTier does not distinguish additive from destructive writes).",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "properties": {
+          "safetyTier": {
+            "enum": [
+              "write",
+              "exec"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "destructiveHint": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): destructiveHint is false for pure and read.",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "properties": {
+          "safetyTier": {
+            "enum": [
+              "pure",
+              "read"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "destructiveHint": {
+                "const": false
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): idempotentHint is true iff replayPolicy is deterministic or idempotent.",
+      "if": {
+        "required": [
+          "replayPolicy"
+        ],
+        "properties": {
+          "replayPolicy": {
+            "enum": [
+              "deterministic",
+              "idempotent"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "idempotentHint": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): idempotentHint is false when replayPolicy is absent or non-deterministic.",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "not": {
+          "properties": {
+            "replayPolicy": {
+              "enum": [
+                "deterministic",
+                "idempotent"
+              ]
+            }
+          },
+          "required": [
+            "replayPolicy"
+          ]
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "idempotentHint": {
+                "const": false
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): openWorldHint is false iff egress is none.",
+      "if": {
+        "required": [
+          "egress"
+        ],
+        "properties": {
+          "egress": {
+            "const": "none"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "openWorldHint": {
+                "const": false
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "RFC 0204 §D.12 (tool-catalog.md §The descriptor): openWorldHint is true when egress is absent or not none.",
+      "if": {
+        "required": [
+          "annotations"
+        ],
+        "not": {
+          "properties": {
+            "egress": {
+              "const": "none"
+            }
+          },
+          "required": [
+            "egress"
+          ]
+        }
+      },
+      "then": {
+        "properties": {
+          "annotations": {
+            "properties": {
+              "openWorldHint": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
     }
-  ],
-  "x-openwop-seeded-from": "v1"
+  ]
 }

package/schemas/v2/trigger-event.schema.json

@@ -503,6 +503,5 @@
         }
       }
     }
-  ],
-  "x-openwop-seeded-from": "v1"
+  ]
 }

package/schemas/v2/trigger-subscription.schema.json

@@ -73,6 +73,5 @@
       "maxLength": 32,
       "description": "MAY — for `source: \"webhook\"`, an identifier for the signing secret (the `(webhookId, secretFingerprint)` register key). It MUST be a **salted or host-keyed, TRUNCATED** one-way digest (e.g. the first 8–16 hex of `HMAC(hostKey, secret)`) — NOT the raw secret (SR-1) and NOT a full unsalted `SHA256(secret)` (a full unsalted hash of a low-entropy secret is an offline brute-force / confirmation oracle). The `maxLength: 32` ceiling structurally rejects a full 64-hex digest."
     }
-  },
-  "x-openwop-seeded-from": "v1"
+  }
 }

package/schemas/v2/webhook-verification.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/webhook-verification.schema.json",
+  "title": "WebhookVerificationRequest (webhooks.md §Standard Webhooks)",
+  "description": "RFC 0201 §D — the one request a host sends to a subscription URL before answering 201 to a registration that opted into `standard-webhooks-1`. It is not a delivery: it carries no `OpenWOP-Event-Type`, and it is signed with the three Standard Webhooks headers under the secret the registration supplied. The endpoint consents by answering 2xx within 10 s with a JSON body whose `challenge` equals the one sent; anything else refuses the registration `400 webhook_endpoint_unverified`. Served for both majors (v1 `webhooks.md` cites the same $id).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "type",
+    "challenge"
+  ],
+  "properties": {
+    "type": {
+      "const": "openwop.webhook.verification"
+    },
+    "challenge": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,128}$",
+      "description": "A fresh base64url value with at least 128 bits of entropy (22 characters), minted per registration."
+    }
+  }
+}