@bluefly/openstandardagents 0.4.9 → 0.5.1

package/spec/v0.5/agent-builder-openapi.yaml

@@ -0,0 +1,230 @@
+openapi: 3.1.0
+info:
+  title: OSSA Agent Builder API
+  version: 0.5.1
+  description: |
+    Canonical builder API for creating and deploying OSSA agents.
+    Owned by ossa-studio (studio.blueflyagents.com) per OWNERSHIP.md.
+    Triggers ossa-deploy pipeline for build/score/publish lifecycle.
+  contact:
+    name: BlueFly.io
+    url: https://bluefly.io
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:3000
+    description: Local development
+  - url: https://studio.blueflyagents.com
+    description: Production (moved from agents.blueflyagents.com/wizard)
+
+paths:
+  /api/agent-builder/generate:
+    post:
+      summary: Generate an OSSA agent manifest
+      operationId: generateAgent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AgentBuilderRequest'
+      responses:
+        '200':
+          description: Manifest generated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentBuilderResult'
+        '400':
+          description: Invalid request — version gate rejects manifests < ossa/v0.5.0
+        '500':
+          description: Build pipeline error
+
+  /api/agent-builder/deploy:
+    post:
+      summary: Deploy agent via ossa-deploy pipeline
+      operationId: deployAgent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DeployRequest'
+      responses:
+        '202':
+          description: Deploy queued
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DeployResult'
+        '400':
+          description: Invalid manifest or version
+        '503':
+          description: ossa-deploy unavailable
+
+  /api/agent-builder/memory:
+    post:
+      summary: Configure memory tier for an agent
+      operationId: configureMemory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MemoryConfig'
+      responses:
+        '200':
+          description: Memory configured
+        '400':
+          description: Invalid memory config
+
+  /api/agent-builder/options:
+    get:
+      summary: Get all available builder options
+      operationId: getBuilderOptions
+      responses:
+        '200':
+          description: Available options
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BuilderOptions'
+
+components:
+  schemas:
+    AgentBuilderRequest:
+      type: object
+      required: [kind, apiVersion, metadata]
+      properties:
+        kind:
+          type: string
+          enum: [Agent, Task, Workflow]
+        apiVersion:
+          type: string
+          description: Must be ossa/v0.5.0 or later; older versions are rejected
+          example: ossa/v0.5.0
+        metadata:
+          type: object
+          properties:
+            name:
+              type: string
+            displayName:
+              type: string
+            description:
+              type: string
+        spec:
+          type: object
+
+    AgentBuilderResult:
+      type: object
+      properties:
+        manifestYaml:
+          type: string
+        agentName:
+          type: string
+        apiVersion:
+          type: string
+          example: ossa/v0.5.0
+        steps:
+          type: array
+          items:
+            type: object
+            properties:
+              step:
+                type: string
+              stdout:
+                type: string
+              exitCode:
+                type: integer
+
+    DeployRequest:
+      type: object
+      required: [manifestPath, sourceRepo]
+      properties:
+        manifestPath:
+          type: string
+          description: Path to manifest within the source repo
+        sourceRepo:
+          type: string
+        sourceRef:
+          type: string
+          default: main
+        requestedBy:
+          type: string
+        options:
+          type: object
+          properties:
+            score:
+              type: boolean
+              default: true
+            publish:
+              type: boolean
+              default: true
+            openMr:
+              type: boolean
+              default: true
+
+    DeployResult:
+      type: object
+      properties:
+        jobId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued, running, complete, failed]
+        score:
+          type: number
+        artifactUrl:
+          type: string
+          format: uri
+        mrUrl:
+          type: string
+          format: uri
+        duadpDid:
+          type: string
+          nullable: true
+        errors:
+          type: array
+          items:
+            type: string
+        pipelineUrl:
+          type: string
+          format: uri
+
+    MemoryConfig:
+      type: object
+      required: [agentName, tier]
+      properties:
+        agentName:
+          type: string
+        tier:
+          type: string
+          enum: [global, domain, agent]
+        collection:
+          type: string
+          description: 'Naming: global.<collection>, <domain>.<collection>, <domain>.<agent>.<collection>'
+
+    BuilderOptions:
+      type: object
+      properties:
+        apiVersions:
+          type: array
+          items:
+            type: string
+          example: ['ossa/v0.5.0', 'ossa/v0.5.1']
+        kinds:
+          type: array
+          items:
+            type: string
+          example: [Agent, Task, Workflow]
+        platforms:
+          type: array
+          items:
+            type: string
+          example: [docker, kubernetes, serverless]
+        memoryTiers:
+          type: array
+          items:
+            type: string
+          example: [global, domain, agent]

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

@@ -25,11 +25,12 @@
       "type": "string",
       "enum": [
         "Agent",
+        "Role",
         "Task",
         "Workflow",
         "Flow"
       ],
-      "description": "Resource type: Agent (agentic loops), Task (deterministic steps), Workflow (composition), or Flow (streaming)"
+      "description": "Resource type: Agent (agentic loops), Role (IDE operator overlay), Task (deterministic steps), Workflow (composition), or Flow (streaming)"
     },
     "metadata": {
       "$ref": "#/definitions/Metadata"
@@ -1380,7 +1381,7 @@
     },
     "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.",
+      "description": "Reasoning pattern, thought trace configuration, governance, session capabilities, hypothesis behavior, and alignment gates for auditable agent cognition (v0.5.0 draft). First-class spec-level primitive for NIST/FedRAMP alignment.",
       "properties": {
         "pattern": {
           "type": "string",
@@ -1424,6 +1425,37 @@
             "audit_required": { "type": "boolean", "default": false }
           },
           "additionalProperties": false
+        },
+        "session": {
+          "type": "object",
+          "description": "Session capabilities for collaborative multi-agent interactions",
+          "properties": {
+            "joinable": { "type": "boolean", "description": "Can this agent join collaborative sessions" },
+            "maxConcurrent": { "type": "integer", "minimum": 1, "default": 1, "description": "Maximum concurrent sessions" },
+            "role": { "type": "string", "enum": ["leader", "contributor", "observer"], "default": "contributor" },
+            "conflictBehavior": { "type": "string", "enum": ["pause", "yield", "escalate"], "default": "pause" }
+          },
+          "additionalProperties": false
+        },
+        "hypothesis": {
+          "type": "object",
+          "description": "Hypothesis declaration behavior for transparent agent reasoning",
+          "properties": {
+            "declaresIntent": { "type": "boolean", "default": true, "description": "Whether the agent declares its intent before acting" },
+            "confidenceThreshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.7, "description": "Minimum confidence to proceed without review" },
+            "requiresAlignment": { "type": "boolean", "default": false, "description": "Must pass alignment gate before executing" }
+          },
+          "additionalProperties": false
+        },
+        "alignmentGate": {
+          "type": "object",
+          "description": "Alignment gate configuration for hypothesis validation before execution",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "arbiter": { "type": "string", "enum": ["human", "compliance-engine", "consensus"], "default": "human" },
+            "timeout": { "type": "string", "default": "5m", "pattern": "^\\d+[smhd]$", "description": "Max wait time for alignment decision" }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/spec/v0.5/extensions/cognition/cognition.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://openstandardagents.org/schemas/v0.5/extensions/cognition.schema.json",
   "title": "OSSA Cognition Extension (v0.5.0 draft)",
-  "description": "Reasoning pattern, thought schema, trace configuration, and governance for auditable agent cognition. First-class spec-level primitive for NIST/FedRAMP alignment.",
+  "description": "Reasoning pattern, thought schema, trace configuration, governance, session capabilities, hypothesis behavior, and alignment gates for auditable agent cognition. First-class spec-level primitive for NIST/FedRAMP alignment.",
   "type": "object",
   "properties": {
     "pattern": {
@@ -88,6 +88,83 @@
         }
       },
       "additionalProperties": false
+    },
+    "session": {
+      "type": "object",
+      "description": "Session capabilities for collaborative multi-agent interactions",
+      "properties": {
+        "joinable": {
+          "type": "boolean",
+          "description": "Can this agent join collaborative sessions"
+        },
+        "maxConcurrent": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Maximum number of concurrent sessions this agent can participate in"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["leader", "contributor", "observer"],
+          "default": "contributor",
+          "description": "Default role this agent assumes in collaborative sessions"
+        },
+        "conflictBehavior": {
+          "type": "string",
+          "enum": ["pause", "yield", "escalate"],
+          "default": "pause",
+          "description": "How the agent handles conflicts during collaborative sessions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "hypothesis": {
+      "type": "object",
+      "description": "Hypothesis declaration behavior for transparent agent reasoning",
+      "properties": {
+        "declaresIntent": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the agent declares its intent before acting"
+        },
+        "confidenceThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.7,
+          "description": "Minimum confidence score required to proceed without review"
+        },
+        "requiresAlignment": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the agent must pass an alignment gate before executing hypotheses"
+        }
+      },
+      "additionalProperties": false
+    },
+    "alignmentGate": {
+      "type": "object",
+      "description": "Alignment gate configuration for hypothesis validation before execution",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the alignment gate is active"
+        },
+        "arbiter": {
+          "type": "string",
+          "enum": ["human", "compliance-engine", "consensus"],
+          "default": "human",
+          "description": "Who or what arbitrates alignment decisions"
+        },
+        "timeout": {
+          "type": "string",
+          "default": "5m",
+          "pattern": "^\\d+[smhd]$",
+          "description": "Maximum time to wait for alignment decision (e.g. 5m, 30s, 1h)"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/spec/v0.5/extensions/economics/context-pack.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.5.0/context-pack.schema.json",
+  "title": "OSSA v0.5.0 Context Pack Schema",
+  "description": "ContextPack defines a reusable, versioned, and token-scored bundle of context to reduce redundancy and increase determinism.",
+  "type": "object",
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v0\\.5.*$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "ContextPack"
+    },
+    "metadata": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "namespace": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": [
+        "content"
+      ],
+      "properties": {
+        "content": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "type",
+              "value"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "text",
+                  "code",
+                  "file",
+                  "embedding",
+                  "reference",
+                  "dynamic-query"
+                ]
+              },
+              "value": {
+                "type": "string"
+              },
+              "token_score": {
+                "type": "integer",
+                "description": "The measured token cost of this specific content block."
+              },
+              "metadata": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "total_tokens": {
+          "type": "integer"
+        },
+        "ttl_seconds": {
+          "type": "integer",
+          "default": 3600
+        },
+        "compression_policy": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/spec/v0.5/extensions/economics/execution-profile.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.5.0/execution-profile.schema.json",
+  "title": "OSSA v0.5.0 Execution Profile Schema",
+  "description": "ExecutionProfile defines the runtime economic and performance policy for an agent execution. It abstracts model selection into intent-based profiles.",
+  "type": "object",
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v0\\.5.*$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "ExecutionProfile"
+    },
+    "metadata": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "namespace": {
+          "type": "string"
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": [
+        "profile_type"
+      ],
+      "properties": {
+        "profile_type": {
+          "type": "string",
+          "enum": [
+            "micro-audit",
+            "fast-route",
+            "balanced-work",
+            "deep-reason",
+            "long-context",
+            "strict-structured",
+            "human-gated"
+          ]
+        },
+        "economics": {
+          "type": "object",
+          "properties": {
+            "cost_ceiling_usd": {
+              "type": "number",
+              "minimum": 0
+            },
+            "context_budget_tokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "compute_budget_units": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "token_sovereignty": {
+              "type": "string",
+              "enum": [
+                "provider-managed",
+                "local-encrypted",
+                "ephemeral"
+              ]
+            }
+          }
+        },
+        "performance": {
+          "type": "object",
+          "properties": {
+            "latency_target_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "priority": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100
+            }
+          }
+        },
+        "reliability": {
+          "type": "object",
+          "properties": {
+            "max_retries": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "failure_semantics": {
+              "type": "string",
+              "enum": [
+                "fail-fast",
+                "graceful-degradation",
+                "retry-with-fallback"
+              ]
+            },
+            "escalation_rules": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "on_failure": {
+                    "type": "string"
+                  },
+                  "action": {
+                    "type": "string",
+                    "enum": [
+                      "retry",
+                      "fail",
+                      "escalate-to-human",
+                      "fallback-profile"
+                    ]
+                  },
+                  "fallback_profile_id": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "audit": {
+          "type": "object",
+          "properties": {
+            "replay_required": {
+              "type": "boolean",
+              "default": false
+            },
+            "compression_policy": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/spec/v0.5/extensions/economics/failure-semantics.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schema.openstandardagents.org/v0.5.0/extensions/economics/failure-semantics.json",
+  "title": "Failure Semantics",
+  "description": "Standardized failure classes for agent executions.",
+  "type": "object",
+  "properties": {
+    "failure_class": {
+      "type": "string",
+      "enum": [
+        "context_insufficient",
+        "policy_denied",
+        "budget_exceeded",
+        "capability_unavailable",
+        "projection_conflict",
+        "state_challenged",
+        "confidence_too_low",
+        "human_required",
+        "provider_degraded"
+      ]
+    },
+    "details": {
+      "type": "string"
+    },
+    "recoverable": {
+      "type": "boolean"
+    },
+    "escalation_path": {
+      "type": "string"
+    }
+  }
+}