@openwop/spec-artifacts 2.0.0-rc.0

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

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/conversation-turn.schema.json",
+  "title": "ConversationTurn",
+  "description": "One turn in a multi-turn conversation. Structural superset of `ConversationMessage` (RFC 0002 §G — append-only, idempotent on `messageId`, replay-deterministic). Adds `role`, optional `agent` reference, and `turnIndex` discriminators. Folds through the existing `applyMessage` reducer unchanged. See RFC 0005 §C.",
+  "type": "object",
+  "required": [
+    "messageId",
+    "from",
+    "content",
+    "ts",
+    "role",
+    "turnIndex"
+  ],
+  "properties": {
+    "messageId": {
+      "type": "string",
+      "description": "Dedup key. Producers MUST construct a deterministic id so re-folding is idempotent. Recommended encoding: `${conversationId}:${turnIndex}:${role}` (e.g., `run-abc:n1:0:7:agent`).",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "from": {
+      "type": "string",
+      "description": "Sender identity. Either an agent ID (RFC 0002 §A1) or the literal `'user'` for human-originated turns.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "to": {
+      "type": "string",
+      "description": "Optional addressee. Absent = broadcast to the conversation's group (or the run's default participants).",
+      "maxLength": 256
+    },
+    "groupId": {
+      "type": "string",
+      "description": "Optional shared-agent group ID. When set, the turn is scoped to the `shared:<groupId>` agent context per RFC 0002 §A8.",
+      "maxLength": 256
+    },
+    "content": {
+      "description": "Opaque turn content. Protocol does not standardize the shape; hosts use Zod schemas at the application layer for structured turns. Pass-through for any JSON value.",
+      "type": [
+        "object",
+        "array",
+        "string",
+        "number",
+        "boolean",
+        "null"
+      ]
+    },
+    "ts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Turn timestamp (ms epoch). Caller's clock; replay carries through unchanged for determinism."
+    },
+    "role": {
+      "type": "string",
+      "enum": [
+        "user",
+        "agent",
+        "system"
+      ],
+      "description": "Discriminator distinguishing human-originated turns (`'user'`), AI-agent-originated turns (`'agent'`), and host-emitted procedural turns (`'system'` — e.g., `'conversation timed out'`)."
+    },
+    "agent": {
+      "type": "object",
+      "description": "Optional agent reference (RFC 0002 §A1 `AgentRef`) for `role: 'agent'` turns. The same shape RFC 0002 reserves on `RunSnapshot.agent` and `node.started.payload.agent` — propagated through inheritance.",
+      "properties": {
+        "agentId": {
+          "$ref": "ids.schema.json#/$defs/agentId"
+        },
+        "agentSharing": {
+          "type": "string",
+          "enum": [
+            "isolated",
+            "shared",
+            "shared:%shared%"
+          ],
+          "description": "Per RFC 0002 §A8 — `shared:<groupId>` requires a `groupId` field on the message."
+        },
+        "memoryRef": {
+          "type": "string",
+          "description": "Opaque memory reference per RFC 0002 §A + RFC 0004 §A. Resolves to `MemoryEntry[]` via host `MemoryAdapter` for cross-run conversation continuity."
+        },
+        "model": {
+          "type": "object",
+          "description": "RFC 0109 — OPTIONAL provenance: which model produced this `role: 'agent'` turn. NON-SECRET, NON-PII: provider + model identifiers ONLY (`additionalProperties: false` forbids any credential/endpoint/prompt leaking in — the SR-1 secret-redaction guard). Stamped at emit; read VERBATIM on `:fork` (never re-resolved). A host that stamps it MUST advertise `conversationTurnModelProvenance.supported: true`. Absent ⇒ no advertisement; clients MUST tolerate its absence.",
+          "additionalProperties": false,
+          "required": [
+            "provider",
+            "model"
+          ],
+          "properties": {
+            "provider": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "description": "Provider identifier (e.g. `anthropic`, `openai`, `google`). Non-secret."
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256,
+              "description": "Model identifier as the provider names it (e.g. `claude-opus-4-8`). Non-secret."
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "turnIndex": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "0-based index within the conversation. `conversation.opened.initialTurn` carries `turnIndex: 0`; subsequent `conversation.exchanged` turns increment monotonically; `conversation.closed.finalTurn` carries the highest index."
+    },
+    "speakerId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "RFC 0101. Stable speaker identity of this turn — the roster INSTANCE id of the agent that produced it (the `host:<id>` AgentRef agentId per `agent-roster-entry.schema.json` §A / RFC 0086), NOT the manifest/class `AgentRef.agentId`. REQUIRED when `role: 'agent'` (the conditional below) so that 'turn N was spoken by agent X' is an observable, replay-stable, cross-host-projectable fact in a multi-party transcript. When a `participants` roster is declared on `conversation.opened` (RFC 0101), `speakerId` MUST be a member of that roster; a turn whose `speakerId` is not a participant MUST be rejected (host-enforced, capability-gated on `multiPartyConversation.supported`). For `role: 'user'` / `role: 'system'` turns the field is OPTIONAL and carries no normative meaning. Additive-safe: pre-RFC-0101 `role: 'agent'` turns that omit it are accepted by hosts that do NOT advertise `multiPartyConversation`."
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "RFC 0101 — agent turns MUST carry speaker attribution. Conditional (not unconditional `required`) so the field is only mandatory for `role: 'agent'`; `user`/`system` turns and pre-RFC-0101 producers on non-multi-party hosts are unaffected. Capability-gated: hosts enforce this only when advertising `multiPartyConversation.supported` (capabilities.schema.json).",
+      "if": {
+        "properties": {
+          "role": {
+            "const": "agent"
+          }
+        },
+        "required": [
+          "role"
+        ]
+      },
+      "then": {
+        "required": [
+          "speakerId"
+        ]
+      }
+    }
+  ],
+  "examples": [
+    {
+      "$comment": "RFC 0101 POSITIVE — an agent turn in a multi-party council carrying speaker attribution (the roster instance id).",
+      "messageId": "council-q1:1:agent",
+      "from": "host:advisor-cfo",
+      "content": "From a cash-runway view I'd push the launch one quarter.",
+      "ts": 1718900000000,
+      "role": "agent",
+      "turnIndex": 1,
+      "speakerId": "host:advisor-cfo"
+    },
+    {
+      "$comment": "RFC 0101 POSITIVE — a user turn; speakerId is OPTIONAL for non-agent roles and omitted here.",
+      "messageId": "council-q1:0:user",
+      "from": "user",
+      "content": "Should we launch in Q3 or Q4?",
+      "ts": 1718900000000,
+      "role": "user",
+      "turnIndex": 0
+    }
+  ],
+  "$comment": "RFC 0101 NEGATIVE (covered by the `allOf`/`if` conditional + conversation scenarios, NOT validatable as an `examples[]` entry which must be VALID): a `{ role: 'agent', ... }` turn that OMITS `speakerId` MUST FAIL validation; see conformance/src/scenarios/multi-party-conversation-shape.test.ts.",
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/credential-provenance.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/credential-provenance.schema.json",
+  "title": "CredentialProvenance",
+  "description": "RFC 0079 §A. Metadata ABOUT a host-issued credential (an RFC 0046 stored reference or an RFC 0047 OAuth token) attached at the tool/egress boundary — never the secret value (SR-1; reuses the RFC 0046 `credential-payload-redaction` posture). Travels with the egress decision, not the credential material. The §C audience-binding MUST is evaluated against `audiences`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credentialId",
+    "issuer",
+    "audiences"
+  ],
+  "properties": {
+    "credentialId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable host-issued id for the credential (the RFC 0046 `ref`, or an OAuth-grant id). Correlates audit + the Keys-page view. NOT the secret value."
+    },
+    "issuer": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Who minted/owns the credential — the host itself (`host`), an RFC 0047 OAuth provider id, or a BYOK principal (RFC 0046). Lets a consumer distinguish host-managed from caller-supplied credentials."
+    },
+    "audiences": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "REQUIRED. The destination hosts/domains (or destination-class ids) the credential is valid for. The §C binding MUST is evaluated against this list — a credential MUST NOT be attached to an egress outside its audiences. Matching is exact host or an explicit `*.domain` suffix form (no arbitrary regex — injection risk; RFC 0079 §UQ1)."
+    },
+    "scopes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true,
+      "description": "MAY — RFC 0049 scopes the credential grants (e.g. `egress:stripe:charge`)."
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "MAY — credential expiry; an expired credential MUST NOT be attached (deny, `reason: \"expired\"`)."
+    },
+    "redactionPolicy": {
+      "type": "string",
+      "enum": [
+        "always",
+        "hash",
+        "host-policy"
+      ],
+      "description": "MAY — how the credential surfaces in logs/events. `always`: never appears (default posture, SR-1); `hash`: an SR-1-redacted digest MAY appear; `host-policy`: host-defined. The secret value itself is NEVER on the wire regardless."
+    },
+    "auditCorrelationId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MAY — id correlating this credential's egress decisions across the run's `egress.decided` events + the host audit log."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/credential-reference.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/credential-reference.schema.json",
+  "title": "CredentialReference",
+  "description": "RFC 0046. An opaque, host-issued handle to a stored credential. This is the ONLY credential artifact permitted on the wire — it NEVER carries key material. The host's host.credentials resolver dereferences it into the node sandbox at execution time (SECURITY invariant `credential-payload-redaction`).",
+  "type": "object",
+  "required": [
+    "ref"
+  ],
+  "properties": {
+    "ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque host-issued identifier, e.g. `cred_a3b9c2`. Hosts MUST NOT encode secret material in the ref."
+    },
+    "scope": {
+      "type": "string",
+      "enum": [
+        "user",
+        "workspace",
+        "tenant"
+      ],
+      "description": "Resolution scope. MUST match a scope in `capabilities.credentials.scopes`. Absent ⇒ the host's default scope."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/debug-bundle.schema.json

@@ -0,0 +1,312 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/debug-bundle.schema.json",
+  "title": "RunDebugBundle",
+  "description": "Portable JSON export of a single run's diagnostic state. See spec/v1/debug-bundle.md. Additive over v1 per COMPATIBILITY.md §2.1: optional endpoint; hosts MAY omit.",
+  "type": "object",
+  "required": [
+    "bundleVersion",
+    "generatedAt",
+    "host",
+    "run",
+    "events",
+    "redactionApplied",
+    "redactionMode"
+  ],
+  "properties": {
+    "bundleVersion": {
+      "const": "2",
+      "description": "RFC 0172 §B axis 10 — one const family; this bundle is \"2\" in v2."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the host generated this response."
+    },
+    "host": {
+      "type": "object",
+      "description": "Identifies the host that produced the bundle.",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "vendor": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "run": {
+      "type": "object",
+      "description": "Run snapshot — same shape as GET /v1/runs/{runId}. See run-snapshot.schema.json.",
+      "required": [
+        "runId",
+        "workflowId",
+        "status"
+      ],
+      "properties": {
+        "runId": {
+          "$ref": "ids.schema.json#/$defs/runId"
+        },
+        "workflowId": {
+          "$ref": "ids.schema.json#/$defs/workflowId"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled",
+            "waiting-approval",
+            "waiting-clarification"
+          ]
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "endedAt": {
+          "oneOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "error": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code"
+              ],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "message": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "variables": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "currentNodeId": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "nodeStates": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "metrics": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "events": {
+      "type": "array",
+      "description": "Full event log for this run, in order. Each entry follows run-event.schema.json.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "sequence": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": 0
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "type": {
+            "type": "string",
+            "minLength": 1
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "nodeId": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "data": {}
+        },
+        "additionalProperties": false
+      }
+    },
+    "spans": {
+      "type": "array",
+      "description": "OTel-format spans per spec/v1/observability.md. Empty array if host doesn't emit spans.",
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "spanId": {
+            "$ref": "ids.schema.json#/$defs/spanId"
+          },
+          "parentSpanId": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "oneOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "attributes": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "description": "Aggregate metrics for the run.",
+      "properties": {
+        "openwopCost": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "usd": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "tokens": {
+                  "type": "object",
+                  "properties": {
+                    "input": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "output": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "model": {
+                  "type": "string"
+                },
+                "provider": {
+                  "type": "string"
+                },
+                "duration_ms": {
+                  "type": "number",
+                  "minimum": 0
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "nodeCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "eventCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "MUST equal events.length per spec/v1/debug-bundle.md."
+        }
+      },
+      "additionalProperties": false
+    },
+    "redactionApplied": {
+      "type": "boolean",
+      "description": "True if any field in this bundle was masked/omitted/hashed by the host's redaction harness."
+    },
+    "redactionMode": {
+      "type": "string",
+      "enum": [
+        "mask",
+        "omit",
+        "hash",
+        "passthrough"
+      ],
+      "description": "Masking mode in effect per capabilities.compliance.defaultMode."
+    },
+    "truncated": {
+      "type": "boolean",
+      "description": "True when the bundle was truncated to fit the host's size cap."
+    },
+    "truncatedReason": {
+      "type": "string",
+      "description": "Why truncation occurred (e.g., 'events_truncated_to_size_cap')."
+    }
+  },
+  "additionalProperties": false
+}