@bluefly/openstandardagents 0.4.5 → 0.4.8

package/dist/spec/v0.5/agent.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://openstandardagents.org/schemas/v0.5/agent.schema.json",
-  "title": "OSSA v0.5 Agent Manifest Schema",
-  "description": "Open Standard for Software Agents (OSSA) v0.5 - Extends v0.4 with Agent Identity, Security Posture, and Protocol Declarations. Backward compatible with v0.4 manifests.",
+  "$id": "https://openstandardagents.org/schemas/v0.4.6/agent.schema.json",
+  "title": "OSSA v0.4.6 Agent Manifest Schema",
+  "description": "Open Standard for Software Agents (OSSA) v0.4.6 - Extends v0.4 with Agent Identity, Security Posture, and Protocol Declarations. Backward compatible with v0.4 manifests.",
   "type": "object",
   "required": [
     "apiVersion",
@@ -13,10 +13,10 @@
     "apiVersion": {
       "type": "string",
       "pattern": "^ossa/v(0\\.5(\\.[0-9]+(-[a-zA-Z0-9.]+)?)?|0\\.4(\\.[0-9]+(-[a-zA-Z0-9.]+)?)?|0\\.3(\\.[4-9]|\\.[0-9]+(-[a-zA-Z0-9.]+)?)?|0\\.2\\.[2-9](-dev)?|1)(\\.[0-9]+)?(-[a-zA-Z0-9.]+)?$",
-      "description": "OSSA API version (v0.5 introduces identity, security posture, and protocol declarations)",
+      "description": "OSSA API version (v0.4.6 introduces identity, security posture, and protocol declarations)",
       "examples": [
-        "ossa/v0.5",
-        "ossa/v0.5.0",
+        "ossa/v0.4.6",
+        "ossa/v0.4.6.0",
         "ossa/v0.4",
         "ossa/v1"
       ]
@@ -35,15 +35,42 @@
       "$ref": "#/definitions/Metadata"
     },
     "spec": {
-      "description": "Specification varies based on kind"
+      "description": "Specification varies based on kind",
+      "type": "object",
+      "properties": {
+        "user_controls": {
+          "$ref": "#/definitions/UserControls"
+        },
+        "consent": {
+          "$ref": "#/definitions/Consent"
+        },
+        "impact": {
+          "$ref": "#/definitions/Impact"
+        },
+        "transparency": {
+          "$ref": "#/definitions/Transparency"
+        }
+      }
     },
     "security": {
       "$ref": "#/definitions/SecurityPosture",
-      "description": "Security posture metadata defining threat model, capability requirements, sandboxing, and network access constraints (v0.5)"
+      "description": "Security posture metadata defining threat model, capability requirements, sandboxing, and network access constraints (v0.4.6)"
     },
     "protocols": {
       "$ref": "#/definitions/ProtocolDeclarations",
-      "description": "Protocol declarations for MCP, A2A, and ANP interoperability (v0.5)"
+      "description": "Protocol declarations for MCP, A2A, and ANP interoperability (v0.4.6)"
+    },
+    "token_efficiency": {
+      "$ref": "#/definitions/TokenEfficiency",
+      "description": "Token efficiency configuration for cost-optimized execution (v0.4.6)"
+    },
+    "cognition": {
+      "$ref": "#/definitions/Cognition",
+      "description": "Reasoning pattern, trace config, and governance for auditable cognition (v0.5.0 draft)"
+    },
+    "governance": {
+      "$ref": "#/definitions/Governance",
+      "description": "Governance and authorization policies including Cedar pre-execution checks and compliance profiles (v0.4.6)"
     },
     "extensions": {
       "type": "object",
@@ -52,6 +79,10 @@
     },
     "runtime": {
       "description": "Runtime-specific capability bindings (for Task and Workflow kinds)"
+    },
+    "composition": {
+      "$ref": "#/definitions/WorkflowComposition",
+      "description": "Workflow composition with sequential/parallel projection (v0.4.6, when kind is Workflow)"
     }
   },
   "definitions": {
@@ -83,6 +114,86 @@
           "maxLength": 2000,
           "description": "Human-readable description"
         },
+        "uuid": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Optional UUID v4 for stable cross-system reference"
+        },
+        "x-signature": {
+          "type": "object",
+          "description": "Optional cryptographic signature block for NIST CAISI identity alignment and provenance verification",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "Ed25519",
+                "RSA-PSS",
+                "ECDSA",
+                "jwt",
+                "vc",
+                "did"
+              ],
+              "description": "Signature scheme or protocol used"
+            },
+            "value": {
+              "type": "string",
+              "description": "The base64 encoded signature payload"
+            },
+            "publicKey": {
+              "type": "string",
+              "description": "Public key matching the signature, formatted as base64 or PEM"
+            },
+            "issuer": {
+              "type": "string",
+              "description": "Optional DID or URI of the entity that issued the signature for trust path building"
+            },
+            "timestamp": {
+              "type": "string",
+              "format": "date-time",
+              "description": "ISO 8601 timestamp of when the signature was generated"
+            }
+          },
+          "required": [
+            "type",
+            "value",
+            "publicKey"
+          ]
+        },
+        "machine_name": {
+          "type": "string",
+          "pattern": "^[a-z0-9_]+$",
+          "maxLength": 128,
+          "description": "Drupal-friendly machine name (config/entity identifier)"
+        },
+        "signature": {
+          "type": "string",
+          "description": "Optional manifest signature (e.g. Ed25519) for signing"
+        },
+        "sbom_pointer": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional URL or path to SBOM document (e.g. CycloneDX JSON)"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "active",
+            "deprecated",
+            "revoked"
+          ],
+          "default": "active",
+          "description": "Agent status: active, deprecated, revoked"
+        },
+        "revoked_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 when agent was revoked"
+        },
+        "deprecated_message": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Message when status is deprecated"
+        },
         "labels": {
           "type": "object",
           "additionalProperties": {
@@ -100,7 +211,7 @@
         },
         "identity": {
           "$ref": "#/definitions/AgentIdentity",
-          "description": "Agent identity model with namespace, versioned identifier, and publisher information (v0.5)"
+          "description": "Agent identity model with namespace, versioned identifier, and publisher information (v0.4.6)"
         },
         "catalog": {
           "type": "object",
@@ -117,47 +228,95 @@
             },
             "visibility": {
               "type": "string",
-              "enum": ["public", "private", "internal"],
+              "enum": [
+                "public",
+                "private",
+                "internal"
+              ],
               "default": "private",
               "description": "Agent visibility: public (anyone), private (owner only), internal (organization)"
             },
             "categories": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Agent categories (e.g., code-quality, security, devops)"
             },
             "tags": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Searchable tags"
             }
           },
           "additionalProperties": false
         },
+        "mesh_bindings": {
+          "$ref": "#/definitions/MeshBindings",
+          "description": "Spatial and execution bindings for mesh orchestration (e.g., GitLab/Drupal environments)"
+        },
         "agentType": {
           "type": "string",
           "enum": [
-            "claude", "kagent", "openai", "langchain", "crewai",
-            "autogen", "llamaindex", "haystack", "semantic-kernel",
-            "vertex-ai", "bedrock", "pydantic-ai", "swarm", "custom"
+            "claude",
+            "kagent",
+            "openai",
+            "langchain",
+            "crewai",
+            "autogen",
+            "llamaindex",
+            "haystack",
+            "semantic-kernel",
+            "vertex-ai",
+            "bedrock",
+            "pydantic-ai",
+            "swarm",
+            "custom"
           ],
           "description": "Agent runtime platform. Specifies which platform/framework will execute this agent."
         },
         "agentKind": {
           "type": "string",
           "enum": [
-            "assistant", "orchestrator", "worker", "coordinator",
-            "supervisor", "tool", "reviewer", "planner", "executor",
-            "monitor", "analyst", "researcher", "specialist"
+            "assistant",
+            "orchestrator",
+            "worker",
+            "coordinator",
+            "supervisor",
+            "tool",
+            "reviewer",
+            "planner",
+            "executor",
+            "monitor",
+            "analyst",
+            "researcher",
+            "specialist"
           ],
           "description": "Agent functional role. Describes WHAT the agent does in the system."
         }
       },
       "additionalProperties": true
     },
+    "MeshBindings": {
+      "type": "object",
+      "description": "Bindings linking this OSSA agent to its external execution and spatial environments.",
+      "properties": {
+        "source_project_id": {
+          "type": "string",
+          "description": "The numeric or namespaced source project identifier serving as the execution substrate for this agent."
+        },
+        "execution_node_id": {
+          "type": "string",
+          "description": "The UUID representing this agent in the spatial interaction matrix."
+        }
+      },
+      "additionalProperties": false
+    },
     "AgentIdentity": {
       "type": "object",
-      "description": "Agent identity model for unique identification, versioning, and publisher attribution (v0.5). Enables trust chains, agent discovery, and provenance tracking across registries.",
+      "description": "Agent identity model for unique identification, versioning, and publisher attribution (v0.4.6). Enables trust chains, agent discovery, and provenance tracking across registries.",
       "required": [
         "agent_id"
       ],
@@ -166,9 +325,9 @@
           "type": "string",
           "pattern": "^[a-z0-9]([-a-z0-9./]*[a-z0-9])?$",
           "maxLength": 253,
-          "description": "Hierarchical namespace for scoping agent identifiers (e.g., 'blueflyio/platform', 'org.example.agents'). Supports DNS-style or path-style naming.",
+          "description": "Hierarchical namespace for scoping agent identifiers (e.g., 'acme/platform', 'org.example.agents'). Supports DNS-style or path-style naming.",
           "examples": [
-            "blueflyio/platform",
+            "acme/platform",
             "org.example.agents",
             "gitlab.com/my-org/agents"
           ]
@@ -274,14 +433,26 @@
     },
     "SecurityPosture": {
       "type": "object",
-      "description": "Security posture metadata defining the agent's threat model, required capabilities, sandboxing requirements, and network access constraints (v0.5). Enables security-aware orchestration and policy enforcement.",
+      "description": "Security posture metadata defining the agent's threat model, required capabilities, sandboxing requirements, and network access constraints (v0.4.6). Enables security-aware orchestration and policy enforcement.",
       "properties": {
+        "tier": {
+          "type": "string",
+          "enum": [
+            "tier_1_read",
+            "tier_2_write_limited",
+            "tier_3_write_elevated",
+            "tier_4_system_admin"
+          ],
+          "description": "Trust and authorization tier used for Cedar pre-execution policy evaluation and capability constraints."
+        },
         "threat_model": {
           "type": "array",
           "description": "Threat categories this agent is designed to handle or is exposed to. Used by orchestrators for security-aware task routing.",
           "items": {
             "type": "object",
-            "required": ["category"],
+            "required": [
+              "category"
+            ],
             "properties": {
               "category": {
                 "type": "string",
@@ -301,15 +472,27 @@
               },
               "severity": {
                 "type": "string",
-                "enum": ["critical", "high", "medium", "low", "informational"],
+                "enum": [
+                  "critical",
+                  "high",
+                  "medium",
+                  "low",
+                  "informational"
+                ],
                 "description": "Assessed severity level for this threat category"
               },
               "mitigations": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Mitigation strategies implemented for this threat",
                 "examples": [
-                  ["input-validation", "output-filtering", "rate-limiting"]
+                  [
+                    "input-validation",
+                    "output-filtering",
+                    "rate-limiting"
+                  ]
                 ]
               },
               "description": {
@@ -387,7 +570,9 @@
         "sandboxing": {
           "type": "object",
           "description": "Sandboxing requirements for isolating agent execution.",
-          "required": ["required"],
+          "required": [
+            "required"
+          ],
           "properties": {
             "required": {
               "type": "boolean",
@@ -446,7 +631,11 @@
               },
               "description": "Allowlist of domains the agent may connect to. Supports wildcard subdomains (e.g., '*.example.com'). Empty array means no network access.",
               "examples": [
-                ["api.openai.com", "*.anthropic.com", "registry.npmjs.org"]
+                [
+                  "api.openai.com",
+                  "*.anthropic.com",
+                  "registry.npmjs.org"
+                ]
               ]
             },
             "blocked_domains": {
@@ -460,15 +649,29 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": ["https", "http", "wss", "ws", "grpc", "ssh", "stdio"]
+                "enum": [
+                  "https",
+                  "http",
+                  "wss",
+                  "ws",
+                  "grpc",
+                  "ssh",
+                  "stdio"
+                ]
               },
               "uniqueItems": true,
               "description": "Allowed network protocols. Restrict to 'https' for maximum security.",
-              "default": ["https"]
+              "default": [
+                "https"
+              ]
             },
             "egress_policy": {
               "type": "string",
-              "enum": ["allow-all", "allow-list", "deny-all"],
+              "enum": [
+                "allow-all",
+                "allow-list",
+                "deny-all"
+              ],
               "default": "allow-list",
               "description": "Default egress policy. 'allow-list' requires explicit allowed_domains, 'deny-all' blocks all outbound, 'allow-all' permits any outbound."
             }
@@ -477,7 +680,12 @@
         },
         "data_classification": {
           "type": "string",
-          "enum": ["public", "internal", "confidential", "restricted"],
+          "enum": [
+            "public",
+            "internal",
+            "confidential",
+            "restricted"
+          ],
           "default": "internal",
           "description": "Data classification level this agent is authorized to handle. Enforced by orchestrators for data-aware routing."
         },
@@ -513,7 +721,7 @@
     },
     "ProtocolDeclarations": {
       "type": "object",
-      "description": "Protocol declarations for agent interoperability (v0.5). Declares which agent communication protocols this agent supports, enabling automatic discovery and routing by orchestrators.",
+      "description": "Protocol declarations for agent interoperability (v0.4.6). Declares which agent communication protocols this agent supports, enabling automatic discovery and routing by orchestrators.",
       "properties": {
         "mcp": {
           "$ref": "#/definitions/MCPProtocol",
@@ -533,17 +741,26 @@
     "MCPProtocol": {
       "type": "object",
       "description": "Model Context Protocol (MCP) declaration. Specifies MCP server/client capabilities for tool-based interoperability with Claude, Cursor, and other MCP-compatible clients.",
-      "required": ["version"],
+      "required": [
+        "version"
+      ],
       "properties": {
         "version": {
           "type": "string",
           "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
           "description": "MCP protocol version (e.g., '1.0.0', '2025-03-26')",
-          "examples": ["1.0.0", "0.6.0"]
+          "examples": [
+            "1.0.0",
+            "0.6.0"
+          ]
         },
         "role": {
           "type": "string",
-          "enum": ["server", "client", "both"],
+          "enum": [
+            "server",
+            "client",
+            "both"
+          ],
           "default": "server",
           "description": "MCP role: 'server' (exposes tools), 'client' (consumes tools), 'both' (bidirectional)"
         },
@@ -552,7 +769,10 @@
           "description": "MCP server configurations this agent exposes or connects to",
           "items": {
             "type": "object",
-            "required": ["name", "transport"],
+            "required": [
+              "name",
+              "transport"
+            ],
             "properties": {
               "name": {
                 "type": "string",
@@ -560,7 +780,12 @@
               },
               "transport": {
                 "type": "string",
-                "enum": ["stdio", "http", "sse", "streamable-http"],
+                "enum": [
+                  "stdio",
+                  "http",
+                  "sse",
+                  "streamable-http"
+                ],
                 "description": "MCP transport mechanism"
               },
               "url": {
@@ -574,17 +799,23 @@
               },
               "args": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Command arguments (for stdio transport)"
               },
               "tools": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "List of tool names exposed by this server"
               },
               "resources": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "List of resource URIs exposed by this server"
               }
             },
@@ -624,13 +855,18 @@
     "A2AProtocol": {
       "type": "object",
       "description": "Agent-to-Agent (A2A) protocol declaration. Google's standard for agent interoperability, enabling task delegation, status updates, and artifact exchange between agents.",
-      "required": ["version"],
+      "required": [
+        "version"
+      ],
       "properties": {
         "version": {
           "type": "string",
           "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
           "description": "A2A protocol version",
-          "examples": ["0.2.0", "1.0.0"]
+          "examples": [
+            "0.2.0",
+            "1.0.0"
+          ]
         },
         "endpoint": {
           "type": "string",
@@ -657,11 +893,20 @@
               "items": {
                 "type": "object",
                 "properties": {
-                  "id": { "type": "string" },
-                  "name": { "type": "string" },
-                  "description": { "type": "string" }
+                  "id": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "description": {
+                    "type": "string"
+                  }
                 },
-                "required": ["id", "name"]
+                "required": [
+                  "id",
+                  "name"
+                ]
               },
               "description": "Skills advertised via A2A"
             }
@@ -698,7 +943,12 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": ["bearer", "oauth2", "apiKey", "none"]
+                "enum": [
+                  "bearer",
+                  "oauth2",
+                  "apiKey",
+                  "none"
+                ]
               },
               "description": "Supported authentication schemes"
             }
@@ -740,7 +990,10 @@
                 "description": "URL to the verifiable credential document"
               }
             },
-            "required": ["type", "issuer"]
+            "required": [
+              "type",
+              "issuer"
+            ]
           },
           "description": "Verifiable credentials issued to this agent for trust establishment"
         },
@@ -763,6 +1016,541 @@
         }
       },
       "additionalProperties": false
+    },
+    "TokenEfficiency": {
+      "type": "object",
+      "description": "Token efficiency configuration for cost-optimized agent execution",
+      "properties": {
+        "serialization_profile": {
+          "type": "string",
+          "enum": [
+            "full",
+            "compact",
+            "fingerprint"
+          ],
+          "default": "compact",
+          "description": "Manifest serialization profile. full=200-400 tokens (discovery), compact=60-120 tokens (runtime), fingerprint=15-30 tokens (routing)"
+        },
+        "observation_format": {
+          "type": "string",
+          "enum": [
+            "full",
+            "diff",
+            "projected",
+            "summary"
+          ],
+          "default": "projected",
+          "description": "How tool observations are formatted. diff=returns diff not full file. projected=only matched fields. summary=compressed summary."
+        },
+        "budget": {
+          "$ref": "#/definitions/TokenBudget"
+        },
+        "routing": {
+          "$ref": "#/definitions/ModelRouting"
+        },
+        "consolidation": {
+          "$ref": "#/definitions/ConsolidationStrategy"
+        },
+        "compression": {
+          "$ref": "#/definitions/CompressionConfig"
+        },
+        "custom_metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CustomMetric"
+          },
+          "description": "Agent-specific token efficiency metrics"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TokenBudget": {
+      "type": "object",
+      "description": "Token budget allocation and enforcement",
+      "properties": {
+        "max_input_tokens": {
+          "type": "integer",
+          "description": "Maximum input tokens per request"
+        },
+        "max_output_tokens": {
+          "type": "integer",
+          "description": "Maximum output tokens per request"
+        },
+        "allocation_strategy": {
+          "type": "string",
+          "enum": [
+            "equal",
+            "proportional",
+            "adaptive"
+          ],
+          "default": "adaptive",
+          "description": "How budget is divided across pipeline stages"
+        },
+        "cascade": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CascadeStage"
+          },
+          "description": "Model cascade for cost-optimized routing"
+        }
+      }
+    },
+    "CascadeStage": {
+      "type": "object",
+      "description": "A stage in a model cascade pipeline",
+      "required": [
+        "model",
+        "max_complexity"
+      ],
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Model identifier"
+        },
+        "max_complexity": {
+          "type": "string",
+          "enum": [
+            "low",
+            "medium",
+            "high"
+          ],
+          "description": "Maximum complexity this model handles"
+        },
+        "budget_share": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Fraction of total budget allocated to this stage"
+        },
+        "budget_tokens": {
+          "type": "integer",
+          "description": "Absolute token budget for this stage"
+        },
+        "condition": {
+          "type": "string",
+          "description": "Condition expression for when to use this stage"
+        }
+      }
+    },
+    "ModelRouting": {
+      "type": "object",
+      "description": "Intelligent model routing configuration",
+      "properties": {
+        "cascade": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Model tiers in order of cost (e.g., [haiku, sonnet, opus])"
+        },
+        "complexity_threshold": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "description": "Complexity score thresholds between tiers (e.g., [0.3, 0.7])"
+        },
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "cost_optimized",
+            "quality_optimized",
+            "balanced"
+          ],
+          "default": "cost_optimized"
+        }
+      }
+    },
+    "ConsolidationStrategy": {
+      "type": "object",
+      "description": "Trajectory consolidation strategy for multi-turn interactions",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "aggressive",
+            "moderate",
+            "minimal",
+            "none"
+          ],
+          "default": "moderate",
+          "description": "How aggressively to consolidate trajectory history"
+        },
+        "retain": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Fields to always retain (e.g., final_answer, confidence)"
+        },
+        "summarize": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Fields to summarize instead of keeping verbatim"
+        },
+        "drop": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Fields to drop entirely (e.g., raw_observations, intermediate_diffs)"
+        },
+        "accumulate": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Fields to accumulate with a token cap"
+        },
+        "max_accumulated_tokens": {
+          "type": "integer",
+          "default": 5000,
+          "description": "Maximum tokens for accumulated fields"
+        }
+      }
+    },
+    "CompressionConfig": {
+      "type": "object",
+      "description": "Prompt and context compression configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "template",
+            "semantic",
+            "hybrid",
+            "none"
+          ],
+          "description": "Compression approach: template=pattern replacement, semantic=LLMLingua-style, hybrid=both"
+        },
+        "compression_ratio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Target compression ratio (0.2 = 5x compression)"
+        },
+        "min_quality": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.95,
+          "description": "Minimum quality threshold - do not compress if quality drops below this"
+        },
+        "templates": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CompressionTemplate"
+          }
+        }
+      }
+    },
+    "CompressionTemplate": {
+      "type": "object",
+      "required": [
+        "name",
+        "pattern"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "Compact pattern (e.g., scan_ctx[{{lang}}|{{framework}}|{{file_count}}])"
+        },
+        "expands_to": {
+          "type": "string",
+          "description": "Full expansion template"
+        },
+        "savings": {
+          "type": "integer",
+          "description": "Estimated tokens saved per use"
+        }
+      }
+    },
+    "CustomMetric": {
+      "type": "object",
+      "required": [
+        "name",
+        "type"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "counter",
+            "gauge",
+            "histogram"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "Capability": {
+      "type": "object",
+      "description": "Capability declaration with optional fingerprint for routing without loading full descriptions",
+      "properties": {
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Deterministic hash of capability type signature for routing without loading full descriptions"
+        }
+      }
+    },
+    "Cognition": {
+      "type": "object",
+      "description": "Reasoning pattern, thought trace configuration, and governance for auditable agent cognition (v0.5.0 draft). First-class spec-level primitive for NIST/FedRAMP alignment.",
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "enum": ["sequential", "tree_of_thought", "react", "plan_and_execute"],
+          "description": "Cognitive architecture pattern"
+        },
+        "constraints": {
+          "type": "object",
+          "properties": {
+            "max_depth": { "type": "integer", "minimum": 1 },
+            "branching": { "type": "boolean", "default": true },
+            "revision": { "type": "boolean", "default": true },
+            "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "additionalProperties": false
+        },
+        "trace": {
+          "type": "object",
+          "properties": {
+            "format": { "type": "string", "enum": ["otel_spans", "ossa_native", "both"], "default": "both" },
+            "storage": { "type": "string", "enum": ["vector", "graph", "both"], "default": "graph" },
+            "retention": { "type": "string", "pattern": "^(\\d+d|\\d+w|\\d+\\s*days?)$" }
+          },
+          "additionalProperties": false
+        },
+        "governance": {
+          "type": "object",
+          "properties": {
+            "human_review_triggers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "confidence_below": { "type": "number", "minimum": 0, "maximum": 1 },
+                  "contradiction_detected": { "type": "boolean" },
+                  "branch_depth_exceeds": { "type": "integer", "minimum": 1 }
+                },
+                "additionalProperties": true
+              }
+            },
+            "audit_required": { "type": "boolean", "default": false }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "WorkflowComposition": {
+      "type": "object",
+      "description": "Workflow composition with output projection for sequential and parallel agent execution",
+      "properties": {
+        "sequential": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "agent": {
+                "type": "string"
+              },
+              "project": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Output field projection - only these fields pass to the next agent"
+              }
+            }
+          }
+        },
+        "parallel": {
+          "type": "object",
+          "properties": {
+            "shared_context": {
+              "type": "boolean",
+              "default": true,
+              "description": "Deduplicate input context across parallel branches"
+            },
+            "agents": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "Governance": {
+      "type": "object",
+      "description": "Governance and authorization policies mapped to Cedar or OPA engines.",
+      "properties": {
+        "authorization": {
+          "type": "object",
+          "properties": {
+            "clearance_level": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Numeric clearance level required for this agent"
+            },
+            "tool_permissions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "tool": {
+                    "type": "string"
+                  },
+                  "risk_level": {
+                    "type": "string",
+                    "enum": [
+                      "low",
+                      "medium",
+                      "high",
+                      "critical"
+                    ]
+                  },
+                  "requires_approval": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "tool",
+                  "risk_level"
+                ]
+              }
+            },
+            "policy_references": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of Cedar (or other) policy IDs this agent must adhere to"
+            }
+          }
+        },
+        "quality_requirements": {
+          "type": "object",
+          "properties": {
+            "confidence_threshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "test_coverage_threshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "security_score_threshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "max_vulnerability_count": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "compliance": {
+          "type": "object",
+          "properties": {
+            "frameworks": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "SOC2",
+                  "HIPAA",
+                  "GDPR",
+                  "PCI-DSS",
+                  "NIST-800-53"
+                ]
+              }
+            },
+            "data_classification": {
+              "type": "string",
+              "enum": [
+                "public",
+                "internal",
+                "confidential",
+                "restricted"
+              ]
+            },
+            "audit_logging_required": {
+              "type": "boolean"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "UserControls": {
+      "type": "object",
+      "description": "Declares what granular runtime controls the orchestrator has over this agent.",
+      "properties": {
+        "pause": { "type": "boolean", "default": true },
+        "stop": { "type": "boolean", "default": true },
+        "undo": { "type": "boolean", "default": false }
+      },
+      "additionalProperties": false
+    },
+    "Consent": {
+      "type": "object",
+      "description": "Data privacy and telemetry consent properties.",
+      "properties": {
+        "data_collected": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "opt_out": { "type": "boolean", "default": false }
+      },
+      "additionalProperties": false
+    },
+    "Impact": {
+      "type": "object",
+      "description": "Calculated potential blast radius and reversibility of actions.",
+      "properties": {
+        "reversible": { "type": "boolean", "default": true },
+        "blast_radius": {
+          "type": "string",
+          "enum": ["isolated", "local", "system", "external"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "Transparency": {
+      "type": "object",
+      "description": "Transparency and provenance declarations.",
+      "properties": {
+        "self_disclosure": { "type": "boolean", "default": true },
+        "provenance": { "type": "string" }
+      },
+      "additionalProperties": false
     }
   }
 }