@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/connection-pack-manifest.schema.json

@@ -0,0 +1,354 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/connection-pack-manifest.schema.json",
+  "title": "ConnectionPackManifest",
+  "description": "RFC 0095. Manifest for a published OpenWOP connection pack — `pack.json` at the pack root with `kind: \"connection\"`. Peer to and disjoint from `node-pack-manifest.schema.json` (RFC 0003), `prompt-pack-manifest.schema.json` (RFC 0028), and `workflow-chain-pack-manifest.schema.json` (RFC 0013) via the `kind` discriminator. A connection pack is a portable PROVIDER definition — the authorize/token/revoke endpoints, the read/write OAuth scope catalog, and how the integration is reached (an MCP server, an OpenAPI surface, or a core integration node). It carries NO secret: the OAuth client credential is a host concern (RFC 0047), supplied out of band. When installed, it makes an RFC 0045 connector's `auth.provider` / an RFC 0047 `host.oauth` provider string resolve against `provider.id` instead of host-locked code. See `spec/v1/connection-packs.md`.",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "kind",
+    "engines",
+    "provider"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Reverse-DNS pack name per `node-packs.md` §Naming. Reserved scopes are identical (`core.*` / `vendor.<org>.*` / `community.<author>.*` / `private.<host>.*`). Mirror of `prompt-pack-manifest.schema.json#/properties/name`.",
+      "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "version": {
+      "type": "string",
+      "description": "Pack-level SemVer 2.0.0.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "connection",
+      "description": "Pack kind discriminator. MUST be the literal string `\"connection\"` for this schema."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024
+    },
+    "author": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier (e.g., `Apache-2.0`)."
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 64
+      },
+      "maxItems": 50
+    },
+    "engines": {
+      "type": "object",
+      "required": [
+        "openwop"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "openwop": {
+          "type": "string",
+          "description": "SemVer range of the openwop spec version this pack targets."
+        }
+      }
+    },
+    "provider": {
+      "type": "object",
+      "description": "The portable provider definition. Exactly one per connection pack.",
+      "required": [
+        "id",
+        "displayName",
+        "category",
+        "auth",
+        "reach"
+      ],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "$comment": "RFC 0120 UQ1: apiHosts is REQUIRED when reach is openapi (a credentialed REST/OpenAPI egress surface). A pure metadata / mcp / integration provider MAY omit it. The runtime binding-site validator (spec §Manifest item 13) is the complementary check for credentialed-egress paths the manifest cannot see.",
+          "if": {
+            "required": [
+              "reach"
+            ],
+            "properties": {
+              "reach": {
+                "required": [
+                  "openapi"
+                ]
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "apiHosts"
+            ]
+          }
+        }
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Stable provider id an RFC 0045/0047 `provider` string resolves to, e.g. `github`."
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "communication",
+            "docs",
+            "crm",
+            "dev",
+            "storage",
+            "email-calendar",
+            "ticketing",
+            "data-warehouse",
+            "marketing",
+            "finance",
+            "hr",
+            "esignature",
+            "support",
+            "project-management",
+            "payments",
+            "other"
+          ]
+        },
+        "vendor": {
+          "type": "string",
+          "minLength": 1,
+          "description": "RFC 0123. OPTIONAL. The commercial vendor / ecosystem this connector belongs to (e.g. \"Microsoft 365\", \"Google\", \"Workday\"). Presentational grouping ONLY — it is NOT the resolution key (RFC 0047 `provider` still resolves auth). Free-form (not an enum) so a new vendor needs no schema change; a host/registry groups connectors sharing a `vendor` under one heading and MUST fall back to the provider `displayName` when it is absent."
+        },
+        "auth": {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "oauth2",
+                "api_key",
+                "bearer",
+                "basic"
+              ]
+            },
+            "authFlow": {
+              "type": "string",
+              "enum": [
+                "pkce",
+                "client_credentials",
+                "manual",
+                "none"
+              ]
+            },
+            "scopeModel": {
+              "type": "string",
+              "enum": [
+                "groups",
+                "coarse",
+                "capabilities"
+              ],
+              "default": "groups",
+              "description": "`groups` = read/write scope groups (Google/Jira/Graph). `coarse` = a single read-vs-write toggle (Stripe Connect read_only/read_write). `capabilities` = consent is a static developer-portal capability set, not per-request scopes (Notion)."
+            },
+            "endpoints": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Fixed, manifest-declared https endpoints (RFC 0095 §B.3). Never derived from runtime user input — not an SSRF surface.",
+              "properties": {
+                "authorize": {
+                  "type": "string",
+                  "format": "uri",
+                  "pattern": "^https://"
+                },
+                "token": {
+                  "type": "string",
+                  "format": "uri",
+                  "pattern": "^https://"
+                },
+                "revoke": {
+                  "type": "string",
+                  "format": "uri",
+                  "pattern": "^https://"
+                }
+              }
+            },
+            "scopes": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Read/write scope groups. `write` is requested as a SEPARATE re-consent step (RFC 0095 §B.4).",
+              "properties": {
+                "read": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/$defs/ScopeGroup"
+                  }
+                },
+                "write": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/$defs/ScopeGroup"
+                  }
+                }
+              }
+            },
+            "instanceUrlTemplate": {
+              "type": "string",
+              "description": "For per-account-host providers (Snowflake/NetSuite/ServiceNow): a template the host fills per connection, e.g. `https://{account}.snowflakecomputing.com`. Its presence signals the provider cannot use a single global OAuth app."
+            }
+          }
+        },
+        "reach": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1,
+          "additionalProperties": false,
+          "description": "Exactly ONE of mcp | openapi | integration — which core node injects the resolved credential (RFC 0095 §B.5).",
+          "properties": {
+            "mcp": {
+              "type": "object",
+              "required": [
+                "server"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "server": {
+                  "type": "object",
+                  "required": [
+                    "url",
+                    "transport"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "format": "uri",
+                      "pattern": "^https://"
+                    },
+                    "transport": {
+                      "type": "string",
+                      "enum": [
+                        "http",
+                        "sse"
+                      ]
+                    }
+                  }
+                }
+              }
+            },
+            "openapi": {
+              "type": "object",
+              "required": [
+                "ref"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "description": "URL or in-pack path of the OpenAPI document for core.openwop.http.openapi-call."
+                }
+              }
+            },
+            "integration": {
+              "type": "object",
+              "required": [
+                "node"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "node": {
+                  "type": "string",
+                  "description": "A core.openwop.integration.* node typeId."
+                }
+              }
+            }
+          }
+        },
+        "consumerNodes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The core node typeIds that consume this provider's credential (e.g. core.openwop.mcp.invoke-tool)."
+        },
+        "docsUrl": {
+          "type": "string",
+          "format": "uri"
+        },
+        "apiHosts": {
+          "type": "array",
+          "description": "RFC 0120. API host(s) a host MAY send this provider's resolved credential to for connector egress (RFC 0045). Each entry is a bare registrable hostname — lowercase ASCII, >=2 labels, TLD label beginning with a letter; no scheme, port, path, wildcard, or IP literal. Matched by dot-anchored suffix containment (request host == entry OR ends with '.'+entry); eTLD+1 is the floor and a pack MAY list a tighter exact host (e.g. googleads.googleapis.com). Omitted => no credential-bearing connector egress is reachable (fails closed). REQUIRED when reach is openapi (see the provider-level allOf).",
+          "items": {
+            "type": "string",
+            "format": "hostname",
+            "pattern": "^(?!-)[a-z0-9-]{1,63}(\\.[a-z0-9-]{1,63})*\\.[a-z][a-z0-9-]*$"
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      },
+      "patternProperties": {
+        "^(openwop-|x-|vendor\\.)": {
+          "description": "Vendor / host extension escape hatch (RFC 0138). A property matching `^(x-|vendor\\.)` is a HOST EXTENSION: its semantics are unspecified by this protocol, and a consumer that does not recognize one MUST ignore it rather than reject the pack. Resolves the contradiction in `host-extensions.md` §\"Vendor-prefixed namespaces\", which requires a client receiving an unknown vendor-prefixed field to treat it as opaque — a field that `additionalProperties: false` previously made impossible to carry. SECURITY: an extension value is PACK-AUTHORED, therefore untrusted; \"ignore\" means ignore. See `node-packs.md` §\"Vendor extensions on pack manifests\" and the `pack-manifest-extension-opaque` invariant."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "ScopeGroup": {
+      "type": "object",
+      "required": [
+        "key",
+        "label",
+        "scopes"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9._-]*$"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The provider's raw scope strings, e.g. `https://www.googleapis.com/auth/drive.readonly`."
+        }
+      }
+    }
+  },
+  "patternProperties": {
+    "^(openwop-|x-|vendor\\.)": {
+      "description": "Vendor / host extension escape hatch (RFC 0138). A property matching `^(x-|vendor\\.)` is a HOST EXTENSION: its semantics are unspecified by this protocol, and a consumer that does not recognize one MUST ignore it rather than reject the pack. Resolves the contradiction in `host-extensions.md` §\"Vendor-prefixed namespaces\", which requires a client receiving an unknown vendor-prefixed field to treat it as opaque — a field that `additionalProperties: false` previously made impossible to carry. SECURITY: an extension value is PACK-AUTHORED, therefore untrusted; \"ignore\" means ignore. See `node-packs.md` §\"Vendor extensions on pack manifests\" and the `pack-manifest-extension-opaque` invariant."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

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

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/conversation-event.schema.json",
+  "title": "ConversationEvent",
+  "description": "Discriminated payload for the three new run events RFC 0005 introduces: `conversation.opened`, `conversation.exchanged`, `conversation.closed`. Discriminator is the parent `RunEventDoc.type` field (see `run-event.schema.json`); this schema constrains `payload` shape. The `ConversationTurn` shape is inlined under `$defs` (rather than $ref'd to `conversation-turn.schema.json`) for self-containment under per-file Ajv compile order — keep in sync with `conversation-turn.schema.json`. See RFC 0005 §B.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/ConversationOpenedPayload"
+    },
+    {
+      "$ref": "#/$defs/ConversationExchangedPayload"
+    },
+    {
+      "$ref": "#/$defs/ConversationClosedPayload"
+    }
+  ],
+  "$defs": {
+    "AgentRef": {
+      "type": "object",
+      "description": "RFC 0101. Slim wire-shape projection of an agent's identity. Mirror of the relevant subset of `agent-ref.schema.json`; kept in sync (inlined for self-containment under per-file Ajv compile order, same convention as `ConversationTurn`). Used by `ConversationOpenedPayload.participants` — the cohort permitted to speak. `agentId` here is the roster INSTANCE id (`host:<id>` per RFC 0086) for council members, matching a turn's `speakerId`.",
+      "required": [
+        "agentId"
+      ],
+      "properties": {
+        "agentId": {
+          "$ref": "ids.schema.json#/$defs/agentId"
+        },
+        "name": {
+          "type": "string",
+          "maxLength": 256
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConversationTurn": {
+      "type": "object",
+      "description": "One turn in a multi-turn conversation. Mirror of `conversation-turn.schema.json`; kept in sync. Structural superset of `ConversationMessage` (RFC 0002 §G).",
+      "required": [
+        "messageId",
+        "from",
+        "content",
+        "ts",
+        "role",
+        "turnIndex"
+      ],
+      "properties": {
+        "messageId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "from": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "to": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "groupId": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "content": {
+          "type": [
+            "object",
+            "array",
+            "string",
+            "number",
+            "boolean",
+            "null"
+          ]
+        },
+        "ts": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "user",
+            "agent",
+            "system"
+          ]
+        },
+        "agent": {
+          "type": "object",
+          "properties": {
+            "agentId": {
+              "$ref": "ids.schema.json#/$defs/agentId"
+            },
+            "agentSharing": {
+              "type": "string",
+              "enum": [
+                "isolated",
+                "shared",
+                "shared:%shared%"
+              ]
+            },
+            "memoryRef": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "turnIndex": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "speakerId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "RFC 0101. Roster INSTANCE id of this turn's speaker (`host:<id>` AgentRef per RFC 0086). REQUIRED when `role: 'agent'` (the `allOf`/`if` conditional below). Mirror of `conversation-turn.schema.json`'s `speakerId`; kept in sync."
+        }
+      },
+      "allOf": [
+        {
+          "$comment": "RFC 0101 — agent turns MUST carry speaker attribution. Mirror of `conversation-turn.schema.json`; kept in sync.",
+          "if": {
+            "properties": {
+              "role": {
+                "const": "agent"
+              }
+            },
+            "required": [
+              "role"
+            ]
+          },
+          "then": {
+            "required": [
+              "speakerId"
+            ]
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "ConversationOpenedPayload": {
+      "type": "object",
+      "description": "Payload for `RunEventType: 'conversation.opened'`. Emitted when a node calls `ctx.interrupt({kind: 'conversation', operation: 'start', ...})`. Causation: this event's `causationId` MUST equal the `eventId` of the accompanying `node.suspended`.",
+      "required": [
+        "conversationId",
+        "initialTurn"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "description": "Host-assigned conversation identifier. Deterministic for replay (typically `${runId}:${nodeId}:${attempt}`). Persists across all turns of this conversation.",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "agentId": {
+          "$ref": "ids.schema.json#/$defs/agentId",
+          "description": "Optional. The agent driving this conversation (RFC 0002 §A1). For multi-agent conversations, identifies the conversation owner."
+        },
+        "participants": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/AgentRef"
+          },
+          "description": "RFC 0101. OPTIONAL. The agent cohort permitted to speak in this conversation (multi-party group conversation / advisory council). Each `agentId` is a roster INSTANCE id (`host:<id>` per RFC 0086). When present (and the host advertises `multiPartyConversation.supported`), a turn whose `speakerId` is not a member of this roster MUST be rejected. Disambiguates the singular `agentId` (the owner) from the full speaking cohort. Absent ⇒ no roster enforcement (back-compat: single-agent conversations are unaffected). MVP: declared at open-time only; mid-conversation roster mutation is out of scope (RFC 0101 §Resolved questions)."
+        },
+        "initialTurn": {
+          "$ref": "#/$defs/ConversationTurn"
+        },
+        "schema": {
+          "type": "object",
+          "description": "Optional JSON Schema for resume turn validation. Servers SHOULD validate subsequent `conversation.exchanged` turns against this schema.",
+          "additionalProperties": true
+        },
+        "capabilities": {
+          "type": "array",
+          "description": "Informative host capability hints. Future RFCs may normate values; current namespace is open.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "multi-turn",
+              "streaming"
+            ]
+          }
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "$comment": "RFC 0101 POSITIVE — a 3-agent advisory council opens with a participant roster (instance ids) and a user's opening turn.",
+          "conversationId": "run-abc:n1:0",
+          "agentId": "host:advisor-cfo",
+          "participants": [
+            {
+              "agentId": "host:advisor-cfo",
+              "name": "CFO"
+            },
+            {
+              "agentId": "host:advisor-cmo",
+              "name": "CMO"
+            },
+            {
+              "agentId": "host:advisor-cto",
+              "name": "CTO"
+            }
+          ],
+          "initialTurn": {
+            "messageId": "run-abc:n1:0:user",
+            "from": "user",
+            "content": "Should we launch in Q3 or Q4?",
+            "ts": 1718900000000,
+            "role": "user",
+            "turnIndex": 0
+          }
+        }
+      ]
+    },
+    "ConversationExchangedPayload": {
+      "type": "object",
+      "description": "Payload for `RunEventType: 'conversation.exchanged'`. Emitted on each `operation: 'exchange'` turn round-trip. The `turnIndex` MUST monotonically increase within a `conversationId`.",
+      "required": [
+        "conversationId",
+        "turnIndex",
+        "turn"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "description": "MUST match the `conversation.opened` payload's `conversationId`.",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "turnIndex": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based index within the conversation. `conversation.opened.initialTurn` is `turnIndex: 0`; the first `exchanged` is `turnIndex: 1`; etc."
+        },
+        "turn": {
+          "$ref": "#/$defs/ConversationTurn"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConversationClosedPayload": {
+      "type": "object",
+      "description": "Payload for `RunEventType: 'conversation.closed'`. Emitted on `operation: 'close'`. Terminates the conversation; no further events MAY carry this `conversationId`.",
+      "required": [
+        "conversationId",
+        "turnIndex",
+        "finalTurn"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "description": "MUST match the `conversation.opened` payload's `conversationId`.",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "turnIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total turn count — equal to the closing turn's index."
+        },
+        "finalTurn": {
+          "$ref": "#/$defs/ConversationTurn"
+        },
+        "outcome": {
+          "description": "Opaque host-defined goal value. The conversation's resolved output. Spec does not constrain the shape; hosts MAY layer their own schemas via the `schema` field on `conversation.opened`.",
+          "type": [
+            "object",
+            "array",
+            "string",
+            "number",
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}