@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/agent-deployment.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/agent-deployment.schema.json",
+  "title": "AgentDeployment",
+  "description": "RFC 0082 §C. A per-(agentId, version) deployment record: the host-runtime lifecycle state of one version of a manifest agent (RFC 0003/0070), distinct from the immutable AgentManifest (which is the pack-distribution descriptor) and from the registry's published semver tags (which version EXISTS, not which version SERVES). Holds the deployment `state`, the named `channels` that resolve to this version, the canary traffic share, the rollback pointer, and the provenance (`evalRunId`/`approvalGateId`) of the last transition. Content-free of any manifest body or credential material (SR-1). The record itself is host-internal; this schema is the canonical wire shape a host exposes via GET /v1/agents/{agentId}/deployments (the endpoint lands at Active → Accepted per RFC 0082 §Conformance).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "agentId",
+    "version",
+    "state"
+  ],
+  "properties": {
+    "agentId": {
+      "$ref": "ids.schema.json#/$defs/agentId",
+      "description": "The deployed agent's id (matches `AgentManifest.agentId` / `AgentRef.agentId`)."
+    },
+    "version": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "The concrete agent-definition version this record governs (matches `AgentManifest.version`). A deployment record is per-(agentId, version); a `@channel` reference resolves to exactly one such version per the RFC 0082 §B pin."
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "test",
+        "staged",
+        "active",
+        "paused",
+        "deprecated",
+        "rolled-back"
+      ],
+      "description": "RFC 0082 §C lifecycle state. `draft`: authored, not yet evaluated. `test`: undergoing eval (RFC 0081). `staged`: eval-passed, awaiting production promotion. `active`: serving (optionally at `canaryPercent < 100`). `paused`: temporarily withdrawn, recoverable. `deprecated`: sunset — no new traffic, existing pins honored. `rolled-back`: superseded; `rollbackPointer` names the version that replaced it. Legal transitions: draft→test→staged→active (promotion); active↔paused (operational); active→deprecated (terminal); active→rolled-back (recovery, with `rollbackPointer`)."
+    },
+    "canaryPercent": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "MAY. For an `active` version, the share (0–100) of channel traffic the §B pin draw assigns to THIS version; the remainder goes to the prior `active` version on the same channel. Absent ⇒ 100 (full traffic). A host advertising `agents.deployment.canary: false` MUST reject any value < 100. The per-run draw outcome is the recorded-fact `resolvedAgentVersion` (RFC 0082 §B) — never re-rolled on replay."
+    },
+    "rollbackPointer": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "MAY. For a `rolled-back` version, the version that was restored to `active` in its place (the recovery target). Absent for non-rolled-back records."
+    },
+    "channels": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "MAY. The named deployment channels (e.g. `stable`, `canary`) that resolve to this version. A version MAY be on more than one channel (RFC 0082 UQ#4 — a promoted-to-`stable` version is also resolvable by the reserved `latest` channel = highest active semver). Channel names are host-advertised in `capabilities.agents.deployment.channels`."
+    },
+    "evalRunId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MAY. The RFC 0081 eval run whose `EvalSummary.passed` gated the last promotion into this state (the §E evidence). Content-free reference, not the eval body."
+    },
+    "approvalGateId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MAY. The RFC 0051 `approvalGate` that authorized the last transition (the §E human gate). Content-free reference."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/agent-eval-suite.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/agent-eval-suite.schema.json",
+  "title": "AgentEvalSuite",
+  "description": "RFC 0081 §A. A portable, host-agnostic evaluation suite for a manifest agent (RFC 0003/0070): the tasks, the expected outputs or rubrics, the deterministic tool/memory fixtures, the allowed model classes, and the pass/fail thresholds that answer \"is this agent good enough to deploy?\". Distributed inside a pack tarball and referenced by URI exactly like `systemPromptRef` / `handoff.*SchemaRef` (RFC 0003 §C/§D) — NOT embedded in `AgentManifest`. A host advertising `capabilities.agents.evalSuite.supported: true` executes a suite as an eval run (a `mode: \"eval\"` projection over `POST /v1/runs`, RFC 0081 §B) and terminates with an `eval-summary.schema.json` scorecard. The suite carries NO secret material and NO host-internal identifiers (it is authored offline and shipped in a signed pack).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "suiteId",
+    "version",
+    "modes",
+    "tasks"
+  ],
+  "properties": {
+    "suiteId": {
+      "type": "string",
+      "pattern": "^[a-z0-9.-]+\\.evals\\.[a-z0-9-]+$",
+      "description": "Globally unique suite identifier in the `<scope>.<org>.evals.<name>` convention (e.g. `core.openwop.evals.support-resolver`), mirroring the pack `<scope>.<author>.<pack>` namespace (RFC 0003). The `.evals.` infix distinguishes a suite from an agent/pack id."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "SemVer of the suite. A suite version is pinned on an eval run (carried on `eval.started.suiteVersion` and `eval-summary.suiteVersion`) so a regression comparison (§D `regression` mode) is between like versions."
+    },
+    "targetAgentId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MAY. The `AgentManifest.id` this suite is authored for. Absent ⇒ the suite is agent-agnostic and MAY be pointed at any `agentId` at run time (the run request carries the `agentId`). When present, a host SHOULD reject an eval run whose target `agentId` differs, unless the caller explicitly overrides."
+    },
+    "modes": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "golden",
+          "rubric",
+          "adversarial",
+          "regression",
+          "live-shadow"
+        ]
+      },
+      "description": "The eval modes this suite exercises (RFC 0081 §D closed vocabulary). `golden`: exact / contains / json-match against each task's `expected`. `rubric`: a host-chosen judge scores against weighted criteria (nondeterministic — a recorded-fact score). `adversarial`: tasks probe for unsafe / jailbreak behavior; `safetyFindings` is the primary output. `regression`: re-run against a new agent/model/prompt version and diff scores vs a `baselineRunId` (composes RFC 0054 `:diff`). `live-shadow`: run against LIVE tools/memory instead of `fixtures` — the only mode that bypasses fixture injection; explicitly nondeterministic. A run MUST request only modes the suite declares here AND the host advertises (`capabilities.agents.evalSuite.modes`); an unadvertised mode is rejected at run-create with `400 validation_error`."
+    },
+    "allowedModels": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "reasoning",
+          "writing",
+          "coding",
+          "research",
+          "classification",
+          "general"
+        ]
+      },
+      "description": "MAY. The `AgentManifest.modelClass` values (RFC 0002) the suite is valid for. Absent ⇒ valid for any class. A host SHOULD record the `evaluatedModelClass` on the summary so a score is interpreted against the model it was produced with."
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "MAY. The pass/fail bar for the suite. A task or the aggregate `passed` flag is computed against these. Absent ⇒ the host's default bar (the summary still carries raw scores).",
+      "properties": {
+        "passScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "The minimum aggregate score (0.0–1.0) for `EvalSummary.passed: true`."
+        },
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0,
+          "description": "MAY. The maximum total cost (summed from RFC 0026 `provider.usage`) for a passing run. A run that exceeds it MUST NOT report `passed: true` even if `passScore` is met."
+        },
+        "maxP95LatencyMs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "MAY. The maximum p95 per-task latency for a passing run."
+        }
+      }
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The eval tasks. Each is executed as one child agent invocation (the RFC 0077 `agent.invocation.*` bracket + the existing `agent.*` / `provider.usage` events), scored, and reported via a per-task `eval.scored` event + an `EvalSummary` entry.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "taskId",
+          "input",
+          "expected"
+        ],
+        "properties": {
+          "taskId": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Suite-unique task identifier (kebab-case). Carried verbatim on `eval.scored.taskId` and the per-task summary entry."
+          },
+          "input": {
+            "description": "The run input for the task, validated against the agent's input schema by the host. An opaque object/value — content is task-defined."
+          },
+          "expected": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "kind"
+            ],
+            "description": "How the task is scored. `golden`: deterministic match against `match`. `rubric`: a judge scores against weighted `rubric` criteria.",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "golden",
+                  "rubric"
+                ],
+                "description": "Scoring mode for this task. A suite declaring a non-`golden`/`rubric` `modes` entry (e.g. `adversarial`) still scores each task via one of these two `kind`s."
+              },
+              "match": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "Present when `kind: \"golden\"`. The deterministic expectation.",
+                "properties": {
+                  "strategy": {
+                    "type": "string",
+                    "enum": [
+                      "exact",
+                      "contains",
+                      "json-match"
+                    ],
+                    "description": "`exact`: stringified output equals `value`. `contains`: output contains `value`. `json-match`: output JSON-deep-equals `value` (key order / whitespace insensitive)."
+                  },
+                  "value": {
+                    "description": "The expected value for the strategy. Opaque."
+                  }
+                },
+                "required": [
+                  "strategy",
+                  "value"
+                ]
+              },
+              "rubric": {
+                "type": "array",
+                "minItems": 1,
+                "description": "Present when `kind: \"rubric\"`. Weighted criteria a judge scores the output against; the task score is the weighted sum of met criteria, normalized to 0.0–1.0. Judge selection + scoring is host-internal (nondeterministic — the score is a recorded fact).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "criterion",
+                    "weight"
+                  ],
+                  "properties": {
+                    "criterion": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "A human-readable scoring criterion (e.g. \"cites the 30-day refund window\")."
+                    },
+                    "weight": {
+                      "type": "number",
+                      "minimum": 0,
+                      "maximum": 1,
+                      "description": "Relative weight of this criterion (criteria weights SHOULD sum to 1.0 across the task)."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "fixtures": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "MAY. Deterministic substitutes for live tool/memory I/O so a `golden`/`regression` eval is reproducible. When present, the eval host MUST inject `toolResponses` in place of live tool calls and seed `memorySeed` before the invocation. The `live-shadow` mode is the explicit exception — it ignores `fixtures` and runs against live tools/memory.",
+            "properties": {
+              "toolResponses": {
+                "type": "array",
+                "description": "Canned tool results keyed by tool invocation, injected in place of live tool calls.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "tool"
+                  ],
+                  "properties": {
+                    "tool": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "The `<scope>:<tool-id>` (RFC 0077 `toolAllowlist` / RFC 0078) the response stands in for."
+                    },
+                    "response": {
+                      "description": "The canned result the host returns for that tool. Opaque."
+                    }
+                  }
+                }
+              },
+              "memorySeed": {
+                "type": "array",
+                "description": "Memory entries seeded into the agent's read snapshot before the invocation (RFC 0004 `MemoryAdapter` shape). Tenant-scoped + SR-1-redacted on the host side exactly like any memory write.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/agent-inventory-response.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/agent-inventory-response.schema.json",
+  "title": "AgentInventoryResponse",
+  "description": "Response body for `GET /v1/agents` (RFC 0072 §A). A read-only projection of the manifest agents a host has installed into its AgentRegistry (RFC 0003 / RFC 0070). Served only when the host advertises `capabilities.agents.manifestRuntime.supported: true`. Each entry MUST NOT carry the agent's system-prompt body, resolved handoff schemas, or any credential material (SR-1).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "agents",
+    "total"
+  ],
+  "properties": {
+    "agents": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/AgentInventoryEntry"
+      },
+      "description": "Installed manifest agents, in a stable (agentId-sorted) order."
+    },
+    "total": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Count of installed manifest agents (== agents.length)."
+    }
+  },
+  "$defs": {
+    "AgentInventoryEntry": {
+      "type": "object",
+      "title": "AgentInventoryEntry",
+      "description": "Read projection of an installed `AgentManifest` (agent-manifest.schema.json). Also the body of `GET /v1/agents/{agentId}`.",
+      "additionalProperties": false,
+      "required": [
+        "agentId",
+        "persona",
+        "label",
+        "modelClass",
+        "packName",
+        "packVersion",
+        "toolAllowlist",
+        "hasHandoffSchemas"
+      ],
+      "properties": {
+        "agentId": {
+          "$ref": "ids.schema.json#/$defs/agentId",
+          "description": "The manifest agentId (matches `AgentManifest.agentId` / `AgentRef.agentId`)."
+        },
+        "persona": {
+          "type": "string",
+          "description": "Human-readable agent name from the manifest."
+        },
+        "label": {
+          "type": "string",
+          "description": "Short UI label; falls back to `persona` when the manifest omits `label`."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional one-line catalog summary from the manifest."
+        },
+        "modelClass": {
+          "type": "string",
+          "description": "The manifest's `modelClass` (see agent-manifest.schema.json)."
+        },
+        "packName": {
+          "type": "string",
+          "description": "The pack this agent was installed from."
+        },
+        "packVersion": {
+          "type": "string",
+          "description": "The installed pack version."
+        },
+        "toolAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Tool identifiers the agent MAY invoke (RFC 0002 §A14). The host MUST enforce this at dispatch; an empty array means no tools."
+        },
+        "hasHandoffSchemas": {
+          "type": "boolean",
+          "description": "Whether the manifest declares handoff task/return schemas (the host validates dispatch payloads against them when it advertises `agents.manifestRuntime.handoffValidation`). The schemas themselves are NOT exposed here."
+        },
+        "memoryShape": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The manifest's declared memory shape, when present.",
+          "properties": {
+            "scratchpad": {
+              "type": "boolean"
+            },
+            "conversation": {
+              "type": "boolean"
+            },
+            "longTerm": {
+              "type": "boolean"
+            }
+          }
+        },
+        "confidenceThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "The manifest's `confidence.defaultThreshold`, when present (RFC 0002 §F)."
+        },
+        "degraded": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Capability keys this agent declared as `peerDependenciesMeta.optional` that this host does NOT satisfy, and which are therefore inert for this installation (RFC 0072 §C). Absent or empty means the agent runs at full declared capability here."
+        },
+        "memoryDegraded": {
+          "type": "boolean",
+          "description": "RFC 0080 §C. `true` when this agent's `memoryShape` declares a memory dimension the host's reconciled memory model (RFC 0080 §A) does NOT satisfy — the agent MAY still dispatch at the RFC 0070 floor, but the degradation MUST be observable here (a silent satisfied-looking entry for an unsatisfiable `memoryShape` is non-conformant). Absent ⇒ memory fully satisfied, or an older host that does not compute the projection (consumers treat absence as not-degraded/unknown and MAY probe)."
+        },
+        "degradedMemoryDimensions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "read",
+              "write",
+              "search",
+              "long-term-durability",
+              "compaction",
+              "attribution",
+              "replay-snapshot",
+              "retention"
+            ]
+          },
+          "uniqueItems": true,
+          "description": "RFC 0080 §C. The RFC 0080 §A dimension names (NOT the `memoryShape` keys) this host cannot satisfy for this agent. Present (non-empty) iff `memoryDegraded: true`; OPTIONAL/absent when `memoryDegraded` is false or absent. The dimension name `long-term-durability` is deliberately distinct from the `agents.memoryBackends` *value* `long-term` (a backend id) to avoid wire ambiguity. The §A→`memoryShape` mapping: `longTerm`⇒`long-term-durability`, `scratchpad`/`conversation`⇒`write`+`read` as applicable."
+        },
+        "roster": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "RFC 0086 §B. OPTIONAL/additive. The standing roster INSTANCES of this manifest agent visible to the caller (tenant-scoped per RFC 0074), each with its persona + owned workflow portfolio — so a single GET /v1/agents call surfaces responsibilities without a second round-trip. Present only when the host advertises `capabilities.agents.roster.supported: true`; absent ⇒ no roster surface (today's default).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "rosterId",
+              "persona",
+              "workflows"
+            ],
+            "properties": {
+              "rosterId": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The roster entry's `host:<id>` instance id (agent-roster-entry.schema.json)."
+              },
+              "persona": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The instance's human display name."
+              },
+              "workflows": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "uniqueItems": true,
+                "description": "The workflow ids this instance owns by role (its portfolio)."
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}