@openwop/openwop-conformance 1.0.0

package/schemas/agent-ref.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/agent-ref.schema.json",
+  "title": "AgentRef",
+  "description": "Slim wire-shape projection of an agent's identity. Carried on `RunSnapshot.agent` (the active worker for a run), `RunSnapshot.runOrchestrator` (the supervisor identity for the run's lifetime), `WorkflowNode.agent` (compile-time pinning), and the `agent.*` event family's payload `agentId` field. Distinct from `AgentManifest` (which is the pack-distribution descriptor for an agent definition — see `agent-manifest.schema.json`); `AgentRef` is the runtime projection, not the definition.",
+  "type": "object",
+  "required": ["agentId"],
+  "properties": {
+    "agentId": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 256,
+      "description": "Globally-unique agent identifier. Naming convention mirrors `node-packs.md` §Naming — `<tier>.<org>.<pack>.<agent>` for vendor/community packs (`vendor.acme.support.tier1`); `core.<name>` for spec-canonical agents (`core.chat`, `core.research`); `host:<id>` slim-runtime form for host-internal AgentRefs that don't ship as packs. Host-internal `host:<id>` agents are valid AgentRefs at the wire level but MUST NOT be published as manifests (the `host:` namespace is reserved for runtime synthesis)."
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "Optional human-readable display name. Surfaces in audit / debug-bundle UIs alongside `agentId`. Hosts MAY populate from the agent's `AgentManifest.name` field at projection time; consumers MUST treat absence as 'name unknown' rather than synthesize."
+    },
+    "modelClass": {
+      "type": "string",
+      "enum": [
+        "reasoning",
+        "tool-using",
+        "chat",
+        "code",
+        "vision",
+        "multimodal",
+        "embedding",
+        "classification",
+        "retrieval"
+      ],
+      "description": "Closed enum describing the agent's model-class envelope. Hosts that advertise `capabilities.agents.modelClasses` use this enum to filter agents at install / dispatch time. Vendor extensions ship under `<vendor>.<class>` per `host-extensions.md` (e.g., `openwop.creative-writing`) — vendor-extension values are NOT in the closed enum and MUST surface as unknown to strict consumers."
+    },
+    "memoryRef": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Optional host-defined opaque reference to this agent's long-term memory. Resolved by the host's `MemoryAdapter` (see `agent-memory.md`); the wire-level shape is host-defined per the L2 disposition (mirrors `host-extensions.md` namespace conventions). Hosts that don't implement long-term memory MUST NOT emit this field; hosts that do MUST honor cross-tenant isolation (CTI-1)."
+    },
+    "version": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "Optional version pin for the agent definition (matches `AgentManifest.version`). Lets audit consumers trace which version of an agent definition was active for a given run. Pinning is encouraged for replay determinism; absent values mean 'host's current resolution of the agent'."
+    },
+    "sourceManifestId": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "Optional provenance pointer back to the `AgentManifest.agentId` this AgentRef was projected from. Lets pack-aware hosts trace runtime AgentRefs back to their distribution origin. Absent for host-internal `host:<id>` agents (which have no manifest)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/capabilities.schema.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/capabilities.schema.json",
+  "title": "Capabilities",
+  "description": "openwop capability declaration returned from `GET /.well-known/openwop`. Required v1 fields identify the protocol version, envelope catalog, schema versions, and base limits. Optional v1 fields have stable shapes but MAY be omitted when unsupported.",
+  "type": "object",
+  "required": ["protocolVersion", "supportedEnvelopes", "schemaVersions", "limits"],
+  "properties": {
+    "protocolVersion": {
+      "type": "string",
+      "description": "openwop protocol version the server speaks (e.g., `1.0`). Independent of `engineVersion` (which gates persisted-doc compatibility per version-negotiation.md).",
+      "minLength": 1
+    },
+    "supportedEnvelopes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Envelope `type` strings the engine recognizes (e.g., `prd.create`, `theme.create`, `tasks.create`, `clarification.request`)."
+    },
+    "schemaVersions": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "description": "Active schema version per envelope type (e.g., `{ \"prd.create\": 2 }`)."
+    },
+    "limits": {
+      "type": "object",
+      "required": ["clarificationRounds", "schemaRounds", "envelopesPerTurn"],
+      "properties": {
+        "clarificationRounds": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum total clarification envelopes per task before the engine forces the LLM to proceed."
+        },
+        "schemaRounds": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum total schema-validation rounds per envelope before the node fails."
+        },
+        "envelopesPerTurn": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum total envelopes the LLM may emit in a single chat turn."
+        },
+        "maxNodeExecutions": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Engine-side ceiling on total node executions per run. Acts as the upper bound for `RunOptions.configurable.recursionLimit`. Optional in v1; hosts that advertise it MUST enforce it."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Hard limits enforced by the engine. See capabilities.md §3."
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Optional per-canvas-type or per-workflow extensions (additional envelope types, override limits)."
+    },
+    "implementation": {
+      "type": "object",
+      "description": "Optional v1 server identity (name + version + vendor).",
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "vendor": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "engineVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional v1 server engineVersion (see version-negotiation.md). Independent of `protocolVersion`."
+    },
+    "eventLogSchemaVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional v1 server eventLogSchemaVersion (per-run subcollection contract)."
+    },
+    "supportedTransports": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["rest", "mcp", "a2a", "grpc"] },
+      "description": "Optional v1 transport advertisement. REST is required whether or not this field is present."
+    },
+    "configurable": {
+      "type": "object",
+      "description": "Optional v1 per-run overlay schema — what `RunOptions.configurable` keys this server honors."
+    },
+    "observability": {
+      "type": "object",
+      "description": "Optional v1 hints about emitted spans/metrics/logs. See observability.md."
+    },
+    "minClientVersion": {
+      "type": "string",
+      "description": "Optional v1 minimum client SDK version the server interops with."
+    },
+    "secrets": {
+      "type": "object",
+      "description": "Optional v1 secret/credential resolution advertisement. Clients gate BYOK flows on this. Hosts that don't store credentials return `supported: false`.",
+      "required": ["supported"],
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Host has any secret-resolution at all."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["tenant", "user", "run"]
+          },
+          "uniqueItems": true,
+          "description": "Subset of scopes the host implements. Tenant-scoped secrets are workspace-shared; user-scoped are per-end-user; run-scoped are ephemeral per-run."
+        },
+        "resolution": {
+          "type": "string",
+          "enum": ["host-managed"],
+          "description": "Resolution mode. v1.x supports only `host-managed` (clients reference stored secrets via opaque ids); reserved for future modes."
+        }
+      },
+      "additionalProperties": false
+    },
+    "runtimeCapabilities": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Optional v1 host-advertised opaque capability ids that NodeModules may declare in `NodeModule.requires`. Naming convention: dotted, domain-scoped (`chat.sendPrompt`, `canvas.write`, `secrets.byok`). Provider value shapes are documented per-capability alongside consumers, NOT in the protocol package — the protocol owns the *check*, not domain provider contracts. A client that submits a workflow whose nodes declare a `requires` entry SHOULD first verify the host advertises that capability; a host that lacks a capability MUST refuse to dispatch nodes that declare it, terminating the run with `RunSnapshot.error.code = 'capability_not_provided'`. See `capabilities.md` §\"Runtime capabilities\"."
+    },
+    "aiProviders": {
+      "type": "object",
+      "description": "Optional v1 companion to `secrets`. Advertises which AI providers the host's AI-proxy can route to and which permit BYOK.",
+      "properties": {
+        "supported": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Provider ids the host's AI-proxy can route to. Conventional ids: `anthropic`, `openai`, `gemini`, `mistral`, `cohere`, `vertex`, `bedrock`. Hosts MAY add vendor-prefixed extensions."
+        },
+        "byok": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Subset of `supported` for which BYOK is permitted. Empty array → all calls use platform-managed keys; non-empty → clients MAY pass `ai.credentialRef` in `RunOptions.configurable` for matching providers."
+        },
+        "policies": {
+          "type": "object",
+          "description": "Optional v1 host-side policy enforcement modes for per-provider gating. Omitted → no enforcement; clients see only `optional` semantics. When present, MUST declare `modes` — an empty `{}` is not a valid third state. See `capabilities.md` §`aiProviders.policies`.",
+          "required": ["modes"],
+          "properties": {
+            "modes": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["disabled", "optional", "required", "restricted"] },
+              "uniqueItems": true,
+              "description": "Subset of policy modes this host can enforce. `disabled` = provider may not be used; `optional` = no restriction (default); `required` = BYOK required; `restricted` = model must match the policy's `allowedModels` glob list. Hosts MAY support a subset; clients MUST tolerate any subset."
+            },
+            "scopes": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true,
+              "description": "Resolution layers the host evaluates. Conventional ids: `workspace`, `project`, `canvas-type`. Precedence is host-defined and SHOULD be documented per-deployment."
+            },
+            "errorCode": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Wire-format error code returned on denial. Defaults to `provider_policy_denied`. Reserved for hosts that need a vendor-prefixed alias."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "testing": {
+      "type": "object",
+      "description": "Testing-mode capabilities advertised to clients (closes F1). Lets conformance suites + dev clients discover which mock providers the server supports and which API-key prefix denotes test keys (since mock providers are test-keys-only).",
+      "properties": {
+        "mockProviders": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Mock-provider IDs this server recognizes via `RunOptions.configurable.mockProvider.id`. Servers claiming OpenWOP v1.0 conformance MUST include `stream-text`. Other canonical providers (`tool-calls`, `error`, `usage-only`) are recommended. Implementations MAY add their own (vendor-prefixed)."
+        },
+        "testKeyPrefix": {
+          "type": "string",
+          "description": "API-key prefix that marks a key as test-mode. Mock providers and other test-only surfaces gate on this prefix.",
+          "minLength": 1,
+          "maxLength": 32
+        },
+        "forceEngineVersionRange": {
+          "type": "object",
+          "description": "Range of engine versions the server can be forced into via the `X-Force-Engine-Version` request header (test-keys-only). Used by the conformance suite to verify forward-compat fold-best-effort across the version-negotiation matrix. Closes F5.",
+          "required": ["min", "max"],
+          "properties": {
+            "min": { "type": "integer", "minimum": 0, "description": "Lowest forceable engine version. Typically (current - 1) so back-compat is exercised." },
+            "max": { "type": "integer", "minimum": 0, "description": "Highest forceable engine version. Typically (current + 1) so forward-compat is exercised." }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": true
+    },
+    "fixtures": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Optional v1 fixture workflow IDs the host has seeded. The conformance suite uses this list to decide which fixture-dependent scenarios run vs. skip. Each ID matches a stub at `node_modules/@openwop/openwop-conformance/fixtures/{id}.json`. Hosts MAY advertise vendor-prefixed IDs; clients MUST tolerate unknown IDs. Empty array or absent means the host advertises no fixtures."
+    },
+    "agents": {
+      "type": "object",
+      "description": "Multi-Agent Shift capability block (Phases 1-6). Hosts that implement any multi-agent surface declare it here; pre-MAS hosts omit the block entirely (consumers treat as 'no agent support'). Each field gates a specific conformance scenario class; conformance scenarios skip honestly when the host's advertisement doesn't claim the capability.",
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Master switch for agent identity (Phase 1). When `true`, host accepts run-level `RunSnapshot.agent` / `runOrchestrator` fields, emits `agent.*` events, and honors the confidence-escalation contract."
+        },
+        "profile": {
+          "type": "string",
+          "description": "Optional named capability profile (e.g., `wop-agents-phase-1-skeleton` for identity-only, `wop-agents-full` for orchestrator+dispatch+memory+conversation). Clients pattern-match on profile to gate feature usage."
+        },
+        "modelClasses": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["reasoning", "tool-using", "chat", "code", "vision", "multimodal", "embedding", "classification", "retrieval"]
+          },
+          "uniqueItems": true,
+          "description": "Optional list of `AgentRef.modelClass` values this host supports for hosted agents (Phase 2). Pack manifests whose `modelClass` is not in this list MUST refuse install with `unsupported_model_class`."
+        },
+        "orchestratorPattern": {
+          "type": "string",
+          "description": "Optional orchestration pattern (Phase 2). Canonical: `single`, `delegate`, `delegate.smart`. Vendor extensions ship under `vendor.<host>.<pattern>`."
+        },
+        "memoryBackends": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["long-term"] },
+          "uniqueItems": true,
+          "description": "Optional list of memory backends (Phase 3). `long-term` means the host implements `ExecutionHost.memory` against a durable store with the SR-1 redaction invariant intact end-to-end. Hosts that don't wire `MemoryAdapter` omit this field."
+        },
+        "orchestrator": {
+          "type": "boolean",
+          "description": "Phase 5. When `true`, host advertises that it implements the `core.orchestrator.supervisor` node typeId AND honors the conservative-path suspend semantics (CP-1: low-confidence suspend via `node.suspended { reason: 'low-confidence' }`)."
+        },
+        "dispatch": {
+          "type": "boolean",
+          "description": "Phase 6. When `true`, host advertises that it implements the `core.dispatch` Core typeId AND honors the conservative-path commitment CP-2 (`core.dispatch` MUST NOT mutate the run's DAG mid-run). Implies (but does NOT require) `agents.orchestrator: true`."
+        },
+        "reasoning": {
+          "type": "object",
+          "description": "Phase 1 reasoning-event verbosity configuration.",
+          "properties": {
+            "verbosity": {
+              "type": "string",
+              "enum": ["summary", "full", "off"],
+              "description": "Default reasoning verbosity for `agent.reasoned` events when the run does not override via `RunOptions.configurable.reasoningVerbosity`."
+            },
+            "tokenLimit": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Effective cap on reasoning trace length when verbosity is `summary`. Default 512 tokens."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": true
+    },
+    "conversationPrimitive": {
+      "type": "boolean",
+      "description": "Multi-Agent Shift Phase 4. When `true`, host advertises that it implements the `core.conversationGate` typeId AND honors the `conversation.start` / `conversation.exchange` / `conversation.close` suspend variants. Hosts that don't claim this fall back to `clarification.requested` interrupts for multi-turn user interjections."
+    },
+    "compliance": {
+      "type": "object",
+      "description": "Privacy / compliance behavior advertised to clients (closes O5). Lets consumers know what masking mode is in effect so a `\"[REDACTED]\"` value in event log payloads is recognizable as a server-side mask vs an upstream null.",
+      "properties": {
+        "defaultMode": {
+          "type": "string",
+          "enum": ["mask", "omit", "hash", "passthrough"],
+          "description": "Server's default masking mode for fields marked sensitive. `mask` (default): replace with `\"[REDACTED]\"`. `omit`: drop the field entirely. `hash`: replace with `\"sha256:<hex>\"` for audit-only equality. `passthrough`: record as-is (NOT recommended for production). Workflow authors MAY override per-workflow via `metadata.complianceConfig.maskingMode`. See observability.md §Privacy classification."
+        },
+        "supportedClasses": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["public", "pii", "phi", "pci", "regulated"] },
+          "uniqueItems": true,
+          "description": "Compliance classes this server applies special handling for. A server MAY accept all five classes but only enforce stricter retention on a subset; this field declares the operational reality so workflow authors can choose a server appropriately."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/channel-written-payload.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/channel-written-payload.schema.json",
+  "title": "ChannelWrittenPayload",
+  "description": "Payload of the `channel.written` RunEvent. Carries the WRITE INPUT (pre-reduction), NOT the post-reduction channel state. Replay reconstructs the post-reduction state by folding all `channel.written` events through the declared reducer. See channels-and-reducers.md §Channel write event.",
+  "type": "object",
+  "required": ["channel", "value", "reducer", "writtenAt"],
+  "properties": {
+    "channel": {
+      "type": "string",
+      "description": "Channel name. MUST match a key declared under `WorkflowDefinition.channels`.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "value": {
+      "description": "The write payload (any JSON value). Validated against `ChannelDeclaration.schema` if declared. The semantic shape depends on the channel's reducer — see per-reducer §Examples below.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "reducer": {
+      "type": "string",
+      "description": "The reducer name in effect at write time. Persisted on the event so replays remain deterministic even if the channel's reducer is later renamed/swapped. Canonical names: `replace`, `append`, `merge`, `counter`, `votes`, `feedback`. Custom reducers MUST use `vendor.<org>.<name>`.",
+      "pattern": "^(replace|append|merge|counter|votes|feedback|vendor\\.[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_-]*)$"
+    },
+    "nodeId": {
+      "type": "string",
+      "description": "Optional — node that performed the write. Set for writes from `ctx.channels.write(...)`; absent for system-initiated writes.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "writtenAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp. The engine MAY normalize between this canonical form and platform-specific representations (e.g., Firestore Timestamp)."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The `ChannelDeclaration.schemaVersion` that was live at write time. Persisted on the event so replays + later folds can detect breaking schema changes — the engine validates each event's value against the channel's CURRENT schema and refuses with `channel_schema_breaking_change` when the event's version is older than `current` AND not in `compatibleWith`. Defaults to 1 when omitted (back-compat with pre-C4 servers that didn't track versions). See channels-and-reducers.md §Channel schema migration. (closes C4)"
+    },
+    "sourceEngineId": {
+      "type": "string",
+      "description": "Identifier of the engine instance that performed the write. Set when the writing engine differs from the engine that owns the parent run (e.g., a sub-workflow / cross-canvas-invoke writing to a parent's channel). Absent when the parent's own engine wrote. The fold side uses this to disambiguate origins for `channel-write` trigger filtering (`onlyFrom: 'child'` matches when this field is set and references a known child engine). See channels-and-reducers.md §Distributed reducers. (closes C2)",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "sourceRunId": {
+      "type": "string",
+      "description": "RunId of the cross-engine writer when `sourceEngineId` is set. Absent for owner-engine writes. Lets debugging surfaces (Run Timeline View per replay.md) link the write back to the originating sub-workflow / invoke run. (closes C2)",
+      "minLength": 1,
+      "maxLength": 128
+    }
+  },
+  "additionalProperties": false,
+  "$comment": "Per-reducer expectations on the `value` field (informative — not enforced at this schema level; servers SHOULD validate against `ChannelDeclaration.schema` if declared):\n\n  - `replace`: any value; supersedes prior state.\n  - `append`:  any value; appended to the channel's array. Bounded by `ChannelDeclaration.maxSize` if set.\n  - `merge`:   MUST be a JSON object (`{...}`); shallow-merged into prior state.\n  - `counter`: MUST be a number; added to the running total. Negative allowed.\n  - `votes`:   typically `{voter: string, vote: string|boolean|number, ...}`; the reducer accumulates per-voter latest-wins.\n  - `feedback`: typically `{author: string, text: string, timestamp: string, ...}`; the reducer appends bounded by `maxSize`.\n  - `vendor.*`: implementation-defined; external clients SHOULD treat as `replace` if the reducer name is unknown."
+}

package/schemas/conversation-event.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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": {
+    "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": { "type": "string", "minLength": 1 },
+            "agentSharing": {
+              "type": "string",
+              "enum": ["isolated", "shared", "shared:%shared%"]
+            },
+            "memoryRef": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "turnIndex": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "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": {
+          "type": "string",
+          "description": "Optional. The agent driving this conversation (RFC 0002 §A1). For multi-agent conversations, identifies the conversation owner.",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "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."
+        },
+        "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
+    },
+    "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
+    }
+  }
+}

package/schemas/conversation-turn.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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": {
+          "type": "string",
+          "minLength": 1
+        },
+        "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."
+        }
+      },
+      "additionalProperties": true
+    },
+    "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."
+    }
+  },
+  "additionalProperties": true
+}