@openwop/spec-artifacts 2.0.0-rc.0

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

@@ -0,0 +1,370 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/suspend-request.schema.json",
+  "title": "InterruptPayload",
+  "description": "Wire format for ctx.interrupt(payload) — the canonical HITL primitive. See spec/v1/interrupt.md for semantics. Discriminated by `kind`. The persisted `interrupt.requested` event carries this payload verbatim plus engine-assigned identity fields.",
+  "type": "object",
+  "required": [
+    "kind",
+    "key",
+    "data"
+  ],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "enum": [
+        "approval",
+        "clarification",
+        "external-event",
+        "custom",
+        "conversation.start",
+        "conversation.exchange",
+        "conversation.close",
+        "low-confidence"
+      ],
+      "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)."
+    },
+    "key": {
+      "type": "string",
+      "description": "Deterministic key used to short-circuit on re-entry after process death. If two interrupt() calls in the same run emit the same key, the second returns the cached result of the first. Recommended: ${runId}:${nodeId}:${interruptCount}.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "resumeSchema": {
+      "description": "Optional JSON Schema for resume value. Servers SHOULD validate before returning to the suspended executor.",
+      "type": "object",
+      "additionalProperties": true
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional auto-reject after this duration. Engine throws InterruptTimeoutError when exceeded."
+    },
+    "data": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/ApprovalData"
+        },
+        {
+          "$ref": "#/$defs/ClarificationData"
+        },
+        {
+          "$ref": "#/$defs/ExternalEventData"
+        },
+        {
+          "$ref": "#/$defs/CustomData"
+        },
+        {
+          "$ref": "#/$defs/ConversationStartData"
+        },
+        {
+          "$ref": "#/$defs/ConversationExchangeData"
+        },
+        {
+          "$ref": "#/$defs/ConversationCloseData"
+        },
+        {
+          "$ref": "#/$defs/LowConfidenceData"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ApprovalData": {
+      "type": "object",
+      "description": "Payload for kind='approval'. Uses the canonical 5-action OpenWOP approval vocabulary.",
+      "required": [
+        "artifactId",
+        "artifactType",
+        "title",
+        "actions"
+      ],
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "artifactType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "artifactData": {},
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "accept",
+              "reject",
+              "refine",
+              "edit-accept",
+              "ask"
+            ]
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Allowed actions. Server MUST enforce on resolve. The 'ask' action does NOT exit the suspend — Q&A exchanges accumulate via askService until accept/reject/refine/edit-accept fires. See `interrupt.md` §`ApprovalResume` for the action vocabulary + per-action required fields."
+        },
+        "requiredApprovals": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Multi-approver quorum."
+        },
+        "approversList": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Restrict resolution to these user IDs. Empty/unset = any user with approvals:respond scope."
+        },
+        "rejectionPolicy": {
+          "type": "string",
+          "enum": [
+            "single-veto",
+            "majority"
+          ],
+          "default": "single-veto"
+        },
+        "overrideBypassesQuorum": {
+          "type": "boolean",
+          "default": false,
+          "description": "RFC 0093 §D2 (pins RFC 0051 UQ 2). When `true`, a configured override principal (per `interrupt-profiles.md` §approval-gate `override.requiredRole`) MAY bypass the quorum (`requiredApprovals`) and release the gate alone. Default `false`: an override principal's approval counts as ONE quorum vote; quorum still applies. Optional, additive."
+        },
+        "approverGroupRefs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "RFC 0104 — OPTIONAL, ADVISORY. Opaque group refs whose resolved members are eligible to approve. Like `approversList`, advisory: the host resolves refs against its own identity/RBAC and ENFORCES eligibility at resolve time; the engine treats refs as opaque (no membership resolution in the engine). Capability-gated via `interrupt.approverRouting` (`refKinds` MUST include `group`). Hosts that don't advertise it ignore this field. Membership is resolved at decision time and snapshotted for deterministic replay."
+        },
+        "approverRoleRefs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "RFC 0104 — OPTIONAL, ADVISORY. Opaque role refs whose holders are eligible to approve. Same advisory + host-resolved + opaque-to-engine + decision-time-snapshot semantics as `approverGroupRefs`. Capability-gated via `interrupt.approverRouting` (`refKinds` MUST include `role`)."
+        },
+        "audience": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "RFC 0104 — OPTIONAL, ADVISORY notification-targeting hint: who should be TOLD about this gate, distinct from who MAY approve (the eligibility refs). When OMITTED, the host SHOULD notify the resolved union of the eligibility refs (`approversList` ∪ `approverGroupRefs` ∪ `approverRoleRefs`). When PRESENT, it OVERRIDES that default. Advisory; the host remains the routing authority. Capability-gated via `interrupt.approverRouting.audience`.",
+          "properties": {
+            "subjects": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Opaque subject refs to notify."
+            },
+            "groups": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Opaque group refs to notify."
+            },
+            "roles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Opaque role refs to notify."
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ClarificationData": {
+      "type": "object",
+      "description": "Payload for kind='clarification'. AI/system asks the user for missing context before continuing.",
+      "required": [
+        "questions"
+      ],
+      "properties": {
+        "questions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "question"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "question": {
+                "type": "string",
+                "minLength": 1
+              },
+              "schema": {
+                "type": "object",
+                "description": "Optional JSON Schema for the answer.",
+                "additionalProperties": true
+              }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "contextType": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ExternalEventData": {
+      "type": "object",
+      "description": "Payload for kind='external-event'. Engine waits for an external system to POST to /v1/interrupts/{token}.",
+      "required": [
+        "eventType",
+        "correlation"
+      ],
+      "properties": {
+        "eventType": {
+          "type": "string",
+          "description": "Stable description of what's awaited. Surfaced in admin panels. Examples: 'stripe.checkout.completed', 'calendar.event.confirmed'."
+        },
+        "correlation": {
+          "type": "object",
+          "description": "Opaque correlation payload — whatever the external system needs to match the interrupt back to its source event.",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "CustomData": {
+      "type": "object",
+      "description": "Escape hatch for kinds not yet spec'd. Servers MUST accept and persist; UI rendering and admin tooling are best-effort.",
+      "required": [
+        "customKind"
+      ],
+      "properties": {
+        "customKind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "payload": {}
+      },
+      "additionalProperties": false
+    },
+    "ConversationStartData": {
+      "type": "object",
+      "description": "Payload for kind='conversation.start' (Multi-Agent Shift Phase 4). Opens a new multi-turn conversation context. The host mints a `conversationId` and emits `conversation.opened`; subsequent `conversation.exchange` calls reuse the same id.",
+      "required": [
+        "conversationId"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Opaque conversation identifier. Tenant-unique invariant: hosts MUST ensure no two distinct conversations in the same tenant share an id. Cross-host portability is not normative — `conversationId`s minted by one host MUST NOT be assumed resolvable by another."
+        },
+        "title": {
+          "type": "string",
+          "description": "Optional human-readable conversation title surfaced in host UIs."
+        },
+        "initialPrompt": {
+          "type": "string",
+          "description": "Optional system / agent message that opens the conversation. Folds into the `message` reducer as the first turn."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConversationExchangeData": {
+      "type": "object",
+      "description": "Payload for kind='conversation.exchange' (Multi-Agent Shift Phase 4). Single-turn suspend within an open conversation; resume value MUST validate against the per-turn `outcomeSchema`.",
+      "required": [
+        "conversationId",
+        "prompt"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Active conversation identifier — MUST equal the id minted by a preceding `conversation.start`."
+        },
+        "prompt": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-targeted question for this turn."
+        },
+        "outcomeSchema": {
+          "type": "object",
+          "description": "Optional JSON Schema for the resume value (the user's response). Hosts SHOULD validate before resuming the suspended executor — replay determinism + idempotency require validated outcomes per the Phase-4 H4 disposition.",
+          "additionalProperties": true
+        },
+        "turnIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Optional 0-indexed turn within this conversation. Strictly monotonic when populated; absent values are derived host-side from event-log fold."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConversationCloseData": {
+      "type": "object",
+      "description": "Payload for kind='conversation.close' (Multi-Agent Shift Phase 4). Terminates an open conversation context. Final event in the conversation lifecycle; no further `conversation.exchanged` events MAY follow for this `conversationId` in this run.",
+      "required": [
+        "conversationId"
+      ],
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "reason": {
+          "type": "string",
+          "description": "Optional close rationale (e.g., 'goal-reached', 'max-turns', 'user-cancelled')."
+        }
+      },
+      "additionalProperties": false
+    },
+    "LowConfidenceData": {
+      "type": "object",
+      "description": "Payload for kind='low-confidence' (Multi-Agent Shift Phase 1 — confidence-escalation contract). Emitted by an agent (typically `core.orchestrator.supervisor`) when its `agent.decided.confidence` falls below the run's resolved escalation threshold. Run transitions to `'waiting-approval'`; an operator ratifies the decision via the resume path.",
+      "required": [
+        "agentId",
+        "threshold",
+        "observed"
+      ],
+      "properties": {
+        "agentId": {
+          "$ref": "ids.schema.json#/$defs/agentId",
+          "description": "AgentRef.agentId of the agent that suspended."
+        },
+        "threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Resolved escalation threshold for this run (default 0.7 per Phase-1 disposition; per-run override via `RunOptions.configurable.escalationThreshold`)."
+        },
+        "observed": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "The agent's reported confidence value that triggered the escalation."
+        },
+        "decision": {
+          "description": "Optional sketch of the decision the agent WOULD have emitted at threshold-or-above. Lets operators see the un-ratified choice. Shape mirrors `OrchestratorDecision` or the agent's domain-specific decision type."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

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

@@ -0,0 +1,150 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/tool-descriptor.schema.json",
+  "title": "ToolDescriptor",
+  "description": "RFC 0078. A portable, read-only description of one tool, unifying the five openwop tool surfaces (node-pack / workflow / MCP / connector / host-extension) behind one stable shape. Returned by `GET /v1/tools` + `GET /v1/tools/{toolId}` when the host advertises `capabilities.toolCatalog.supported: true`. The descriptor DESCRIBES a tool; it never carries credential material (SR-1) and is not an invocation path (tools are invoked on their existing surfaces).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "toolId",
+    "source",
+    "safetyTier"
+  ],
+  "properties": {
+    "toolId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable, host-unique tool identifier in the `<scope>:<tool-id>` form RFC 0077 `toolAllowlist` references (`openwop:` core, `mcp:` MCP-namespaced, `connector:` connector, `<vendor>.<host>` / `x-host-<vendor>-*` host-extension). The keyspace SPANS sources so a single allowlist entry resolves to exactly one descriptor; the `<scope>` prefix disambiguates by construction (RFC 0078 §UQ1). MUST be stable across catalog reads for a given host version so an agent's `toolAllowlist` keeps resolving."
+    },
+    "source": {
+      "type": "string",
+      "enum": [
+        "node-pack",
+        "workflow",
+        "mcp",
+        "connector",
+        "host-extension"
+      ],
+      "description": "Which surface backs the tool. `node-pack`: a pack typeId (RFC 0003); `workflow`: a workflow-as-tool (`core.subWorkflow` / RFC 0013); `mcp`: an MCP server tool (`host.mcp`); `connector`: an RFC 0045 connector action; `host-extension`: an `x-host-<vendor>-*` scope (RFC 0069)."
+    },
+    "title": {
+      "type": "string",
+      "description": "MAY — human-readable name for UI."
+    },
+    "description": {
+      "type": "string",
+      "description": "MAY — one-line summary for a tool picker."
+    },
+    "inputSchema": {
+      "type": "object",
+      "description": "MAY — JSON Schema (2020-12) for the tool's arguments. Absent ⇒ opaque/host-interpreted args. RECOMMENDED (not required) to be the RFC 0030 Tier-1 universal subset for tools that feed an LLM tool-call (RFC 0078 §UQ2).",
+      "additionalProperties": true
+    },
+    "outputSchema": {
+      "type": "object",
+      "description": "MAY — JSON Schema for the tool's result.",
+      "additionalProperties": true
+    },
+    "auth": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "MAY — what the caller must supply/hold to invoke. Composes RFC 0049 (scopes) + RFC 0046 (credentials).",
+      "properties": {
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "description": "RFC 0049 scopes the principal MUST hold; per-tool authorization fails closed (RFC 0064 §C)."
+        },
+        "credentialRef": {
+          "type": "boolean",
+          "description": "true ⇒ the tool needs a host-stored credential reference (RFC 0046); the catalog NEVER carries credential material (SR-1)."
+        }
+      }
+    },
+    "egress": {
+      "type": "string",
+      "enum": [
+        "none",
+        "safe-fetch",
+        "host-mediated",
+        "host-owned"
+      ],
+      "description": "MAY — outbound-network posture. `none`: no egress; `safe-fetch`: via the host's RFC 0076 §B `ctx.http.safeFetch` (SSRF-guarded); `host-mediated`: host-proxied non-safeFetch; `host-owned`: the host owns the egress story (e.g. a host-extension)."
+    },
+    "approval": {
+      "type": "string",
+      "enum": [
+        "never",
+        "conditional",
+        "always"
+      ],
+      "description": "MAY — whether invocation requires an RFC 0051 approval interrupt. `conditional` ⇒ host-policy (e.g. over a cost/scope threshold)."
+    },
+    "replayPolicy": {
+      "type": "string",
+      "enum": [
+        "deterministic",
+        "idempotent",
+        "non-deterministic"
+      ],
+      "description": "MAY — replay posture (`replay.md`). `deterministic`: pure/replay-safe; `idempotent`: safe under the Layer-2 idempotency key (`idempotency.md`); `non-deterministic`: the host MUST cache the observable result (RFC 0041 §C) so replay reproduces the sequence."
+    },
+    "safetyTier": {
+      "type": "string",
+      "enum": [
+        "pure",
+        "read",
+        "write",
+        "exec"
+      ],
+      "description": "REQUIRED. The tool's DATA-EFFECT classification: `pure`: no external side effects; `read`: reads external state; `write`: mutates external state; `exec`: arbitrary-command/`exec`-class — per RFC 0069 this MUST have `source: \"host-extension\"` (exec is never protocol-tier). A consumer uses this to gate/warn. The host MUST ASSIGN `safetyTier` explicitly as per-tool metadata; it is NOT derivable from a permission / approval / risk tier — those are an ORTHOGONAL authorization axis (a read-only tool can be high-approval/restricted while being `safetyTier:\"read\"`). A host that mechanically maps its risk tier onto `safetyTier` mis-advertises."
+    },
+    "costHint": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "description": "MAY — advisory cost magnitude for planning UX. Non-normative."
+    },
+    "latencyHint": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "description": "MAY — advisory latency magnitude. Non-normative."
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "RFC 0078 §C-1 / §F-4: an exec-tier tool MUST be host-extension-sourced (RFC 0069 — exec is never protocol-tier).",
+      "if": {
+        "properties": {
+          "safetyTier": {
+            "const": "exec"
+          }
+        },
+        "required": [
+          "safetyTier"
+        ]
+      },
+      "then": {
+        "properties": {
+          "source": {
+            "const": "host-extension"
+          }
+        },
+        "required": [
+          "source"
+        ]
+      }
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}