@openwop/spec-artifacts 2.42.7 → 2.42.8

package/api/v2/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: OpenWOP v2 API
-  version: 2.42.7
+  version: 2.42.8
   summary: REST surface for declaring, executing, suspending, resuming, and observing multi-step workflows.
   description: 'The OpenWOP v2 REST API. Paths are unversioned and served at the bare origin; a client selects a version with
     the `OpenWOP-Version` header from the host''s `protocolVersions[]`. Conformance seams and test-mode operations are not
@@ -76,6 +76,7 @@ paths:
           A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version`
           like every response (versioning.md §1.4).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Capabilities object — see `capabilities.md`.
@@ -137,6 +138,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /workflows/{workflowId}:
     get:
       tags:
@@ -153,6 +155,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/WorkflowId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Workflow definition.
@@ -201,6 +204,7 @@ paths:
           be within `Capabilities.testing.forceEngineVersionRange`. Servers MUST reject it on production API keys with `403
           force_engine_version_forbidden`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -365,6 +369,7 @@ paths:
           - cancelled
         description: Exact-match filter, when advertised in `runList.filters`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: One page of the caller's runs.
@@ -412,6 +417,7 @@ paths:
           A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version`
           like every response (versioning.md §1.4).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Projected run state.
@@ -486,6 +492,7 @@ paths:
           type: string
         description: Resume from sequence after this ID.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: SSE stream. Auto-closes on terminal event. Keep-alive comments every 30s.
@@ -543,6 +550,7 @@ paths:
           default: 30
         description: Seconds to wait for new events. Max 60.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Events after `afterSequence`.
@@ -598,6 +606,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -647,6 +656,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -695,6 +705,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Annotations for the run (tenant-scoped).
@@ -748,6 +759,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -836,6 +848,7 @@ paths:
         description: BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT produce
           a 400.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The resolved, published page for the negotiated locale.
@@ -891,6 +904,7 @@ paths:
         description: For this operation, the page's `pageId`, not its slug; the operation description explains the shared
           name.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '204':
           description: The page, its sections and its locale overlays were deleted.
@@ -944,6 +958,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     post:
       tags:
       - content
@@ -988,6 +1003,7 @@ paths:
           $ref: '#/components/responses/Forbidden'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /content/pages/{pageId}/sections/{sectionId}:
     put:
       tags:
@@ -1017,6 +1033,7 @@ paths:
           type: string
           minLength: 1
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1100,6 +1117,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     put:
       tags:
       - content
@@ -1145,6 +1163,7 @@ paths:
           $ref: '#/components/responses/Forbidden'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /runs:bulk-cancel:
     post:
       tags:
@@ -1165,6 +1184,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1245,6 +1265,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1345,6 +1366,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: 'The run''s immediate parent (`parent: null` for a top-level run).'
@@ -1420,6 +1442,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/{agentId}:
     get:
       tags:
@@ -1447,6 +1470,7 @@ paths:
         description: The manifest agentId. MUST NOT be the reserved literals `roster` or `org-chart`, which name the sibling
           collection routes (`/agents/roster`, `/agents/org-chart`), so `/agents/{agentId}` stays unambiguous.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The agent's inventory entry. When the host advertises `a2a.agentCards`, an entry the host routes a
@@ -1499,6 +1523,7 @@ paths:
           collection routes (`/agents/roster/{rosterId}`, `/agents/org-chart/{departmentId}`), so `/agents/{agentId}/deployments`
           stays unambiguous.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The agent's deployment records (version-sorted).
@@ -1550,6 +1575,7 @@ paths:
         description: The manifest agentId.
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -1639,6 +1665,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/roster/{rosterId}:
     get:
       tags:
@@ -1663,6 +1690,7 @@ paths:
           type: string
         description: The standing instance id (a `host:<id>` AgentRef agentId).
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The roster entry.
@@ -1727,6 +1755,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /agents/org-chart/{departmentId}:
     get:
       tags:
@@ -1758,6 +1787,7 @@ paths:
           default: true
         description: When `false`, the roll-up scopes to direct members only.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The department subtree + responsibility roll-up.
@@ -1813,6 +1843,7 @@ paths:
           true`. Defaults to `standard`. A host that does not advertise `compactView` treats `view=compact` like any unknown
           query parameter and returns the standard view.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: 'The caller''s authorized tool catalog (standard array, or the compact `{ tools: [] }` projection when
@@ -1884,6 +1915,7 @@ paths:
           structural subset) when the host advertises `capabilities.toolCatalog.compactView: true`. Defaults to `standard`.
           A host that does not advertise `compactView` treats `view=compact` like any unknown query parameter.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The tool descriptor (standard, or one `CompactToolDescriptor` when `view=compact`).
@@ -1930,6 +1962,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: The eval run's scorecard.
@@ -1987,6 +2020,7 @@ paths:
         schema:
           type: string
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: 'Structured diff of the two runs. `divergedAtSeq: null` and an empty `eventDiffs` when the logs are
@@ -2048,6 +2082,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -2122,6 +2157,7 @@ paths:
       - $ref: '#/components/parameters/RunId'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         content:
           application/json:
@@ -2192,6 +2228,7 @@ paths:
           minLength: 1
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2290,6 +2327,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     post:
       tags:
       - hitl
@@ -2299,6 +2337,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2351,6 +2390,7 @@ paths:
           type: string
           minLength: 1
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Artifact payload. Under `application/json` the shape is implementation-defined. Under `application/a2a+json`
@@ -2389,6 +2429,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2411,7 +2452,7 @@ paths:
                   type: string
                   description: The host signs payloads with this secret using HMAC-SHA256. REQUIRED in the Standard Webhooks
                     form `whsec_<base64>` (24–64 decoded bytes) when `signatureAlgorithms` lists `standard-webhooks-1`. Never
-                    echoed in any response.
+                    echoed in any response. When omitted, the host generates one and returns it once in the `201` (RFC 0221).
                 tags:
                   type: array
                   items:
@@ -2454,6 +2495,11 @@ paths:
                     items:
                       type: string
                     description: The list the dispatcher will apply; present whenever the request carried `signatureAlgorithms`.
+                  secret:
+                    type: string
+                    minLength: 1
+                    description: 'Present only when the request omitted `secret`: the secret the host generated, returned
+                      this once. A supplied secret is never echoed.'
           headers:
             OpenWOP-Version:
               $ref: '#/components/headers/OpenWOPVersion'
@@ -2494,6 +2540,7 @@ paths:
         description: 'Tenant-bound `<tenantId>/<opaque>` (`identity.md` §5), carried as one path segment: `~`-projected or
           percent-encoded.'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '204':
           description: Unregistered.
@@ -2532,6 +2579,7 @@ paths:
           percent-encoded.'
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2617,6 +2665,7 @@ paths:
           minimum: 0
         description: Last audit-log sequence to include (inclusive). MUST be >= fromSeq.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Verification result.
@@ -2700,6 +2749,7 @@ paths:
           default: 50
         description: Maximum entries per page.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: Paginated list of templates.
@@ -2749,6 +2799,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -2880,6 +2931,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
     put:
       tags:
       - prompts
@@ -2895,6 +2947,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/IdempotencyKey'
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       requestBody:
         required: true
         content:
@@ -3000,6 +3053,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /prompts:render:
     post:
       tags:
@@ -3111,6 +3165,7 @@ paths:
               $ref: '#/components/headers/OpenWOPVersion'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
   /host/effect-seams:
     get:
       tags:
@@ -3133,6 +3188,7 @@ paths:
           $ref: '#/components/responses/Unauthenticated'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3163,6 +3219,7 @@ paths:
           $ref: '#/components/responses/NotFound'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3193,6 +3250,7 @@ paths:
           $ref: '#/components/responses/NotFound'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3238,6 +3296,7 @@ paths:
         description: Opaque cursor from a previous page's `nextCursor`. A cursor minted for another subscription MUST be refused
           `400 validation_error`.
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       responses:
         '200':
           description: One page of dead-lettered deliveries, newest first.
@@ -3285,6 +3344,7 @@ paths:
           $ref: '#/components/responses/Unauthenticated'
       parameters:
       - $ref: '#/components/parameters/OpenWOPVersion'
+      - $ref: '#/components/parameters/OpenWOPClientVersion'
       security:
       - ApiKeyAuth:
         - runs:read
@@ -3300,7 +3360,8 @@ components:
       bearerFormat: API key
       description: OpenWOP API key. The format is implementation-defined; the reference implementation uses `hk_`/`hk_test_`
         prefixes. Each key carries one or more scopes from the canonical vocabulary (`manifest:read`, `runs:create`, `runs:read`,
-        `runs:cancel`, `artifacts:read`, `webhooks:manage`, `approvals:respond`, `audit:read`). See `auth.md`.
+        `runs:cancel`, `artifacts:read`, `webhooks:manage`, `approvals:respond`, `audit:read`). Scope matching is in `spec/v2/core/identity.md`
+        §2.1.
     OAuth2:
       type: oauth2
       description: 'The OAuth 2.0 lane (`auth.lanes[].lane: "oauth2"`). Discovery is RFC 9728 Protected Resource Metadata
@@ -3395,8 +3456,16 @@ components:
       schema:
         type: string
         pattern: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
-      description: Selects one of the host's listed major.minor versions. Absent, the host uses its `preferredVersion`; an
-        unlisted value is 406 protocol_version_unsupported.
+      description: Selects one of the host's listed major.minor versions. Absent, `/.well-known/openwop` uses `preferredVersion`
+        and every other unversioned path is v2; an unlisted value is 406 protocol_version_unsupported.
+    OpenWOPClientVersion:
+      name: OpenWOP-Client-Version
+      in: header
+      required: false
+      schema:
+        type: string
+      description: The protocol version the client implements (versioning.md §1.5). Compared with `minClientVersion` on major.minor.
+        A malformed value is treated as absent and MUST NOT produce a 400. Never selects a contract.
   responses:
     Unauthenticated:
       description: Missing or invalid credential.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/spec-artifacts",
-  "version": "2.42.7",
+  "version": "2.42.8",
   "description": "The OpenWOP machine-readable contract: api/ (OpenAPI, AsyncAPI, the seams profile), schemas/ (v1 and v2 JSON Schemas), the spec/v1 and spec/v2 registries (errors, event codemap, declaration, deprecations, migrations, gaps) and CORPUS-STAMP.json — published from the openwop/openwop corpus tag; the peer dependency @openwop/openwop-conformance digest-checks at start (RFC 0168 §D.2).",
   "license": "Apache-2.0",
   "repository": {

package/schemas/v2/capabilities.schema.json

@@ -7910,7 +7910,7 @@
         "export": {
           "type": "boolean",
           "default": false,
-          "description": "Host can emit an export bundle for the caller's tenant/workspace via `GET /export`."
+          "description": "Host can emit an export bundle for the caller's tenant or workspace (portability.md)."
         },
         "import": {
           "type": "boolean",
@@ -7937,7 +7937,7 @@
         "dryRun": {
           "type": "boolean",
           "default": true,
-          "description": "Import supports a no-write plan preview (`POST /import?dryRun=true`). MUST be true if `import` is true."
+          "description": "Import supports a no-write plan preview. MUST be true if `import` is true."
         }
       },
       "allOf": [