@bluefly/openstandardagents 0.4.9 → 0.5.1

package/dist/spec/extensions/cognition.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openstandardagents.org/schemas/extensions/cognition.schema.json",
+  "title": "OSSA Cognition Extension",
+  "description": "Declares agent session capabilities, hypothesis behavior, and alignment gates for collaborative multi-agent cognition",
+  "type": "object",
+  "properties": {
+    "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/dist/spec/extensions/role-manifest.md

@@ -0,0 +1,188 @@
+# OSSA Role Manifest Extension
+
+**Version:** 0.5.0
+**Status:** Draft
+**Last Updated:** 2026-03-13
+
+## Overview
+
+This extension introduces `kind: Role` as a new OSSA manifest type. Roles define **behavioral overlays** for IDE and CLI agents (Claude Code, Cursor, Codex CLI, etc.) — configuring instructions, tool access, hooks, MCP server connections, and activation conditions.
+
+### Role vs Agent
+
+| Aspect | `kind: Agent` | `kind: Role` |
+|--------|--------------|--------------|
+| **Purpose** | Autonomous agentic loop | Operator context overlay |
+| **Execution** | Runs independently | Applied to an existing agent session |
+| **Lifecycle** | Deployed, scaled, monitored | Activated, composed, switched |
+| **Identity** | Has its own agent ID | Inherits the host agent's identity |
+| **Example** | A code review bot | "Drupal developer" context for Claude Code |
+
+Roles answer the question: *"What context, rules, and tools should an AI coding assistant have when working in this domain?"*
+
+## Manifest Structure
+
+```yaml
+apiVersion: ossa/v0.5
+kind: Role
+metadata:
+  name: <role-name>           # Required: DNS-style identifier
+  version: <semver>           # Recommended: e.g. 1.0.0
+  description: <string>       # Human-readable summary
+  labels:                     # Optional: key-value pairs for filtering
+    platform: claude-code
+    domain: drupal
+  annotations:                # Optional: non-identifying metadata
+    org: example-corp
+spec:
+  role: <string>              # System prompt / persona definition
+  instructions:               # Behavioral instructions
+    preamble: <markdown>      # Prepended to every conversation
+    constraints:              # Hard rules (MUST/MUST NOT)
+      - <string>
+  tools:                      # Tool access configuration
+    allowed: [<string>]       # Allowed tool names
+    denied: [<string>]        # Denied tool names (overrides allowed)
+    skills: [<string>]        # OSSA skill references
+  hooks:                      # Lifecycle hooks
+    on_activate: <string>     # Run when role is activated
+    on_deactivate: <string>   # Run when role is deactivated
+    pre_commit: <string>      # Run before git commits
+    post_save: <string>       # Run after file saves
+  context:                    # Context injection
+    schemas: [<path>]         # JSON/OpenAPI schemas to load
+    files:                    # Files to include in context
+      - path: <glob>
+        description: <string>
+    knowledge: [<path>]       # Knowledge base files (markdown, text)
+  protocols:                  # Protocol connections
+    mcp:                      # Model Context Protocol
+      servers:
+        - name: <string>
+          transport: stdio | sse
+          command: <string>   # For stdio transport
+          args: [<string>]
+          url: <string>       # For SSE transport
+  extends:                    # Role composition
+    - role: <role-name>       # Inherit from another role
+      override: true | false  # Whether to override conflicts (default: false)
+  activation:                 # When this role should activate
+    file_patterns: [<glob>]   # Activate when matching files are open
+    command: <string>         # CLI command to activate (e.g. "/role drupal")
+    env:                      # Environment variable conditions
+      <key>: <value>
+```
+
+## Field Reference
+
+### `spec.role`
+
+A string defining the agent's persona when this role is active. This is the system-level identity statement.
+
+```yaml
+spec:
+  role: |
+    You are a Drupal module developer following Drupal coding standards.
+    You write PHP 8.2+ code with strict typing and dependency injection.
+```
+
+### `spec.instructions`
+
+Structured behavioral instructions.
+
+- **`preamble`**: Markdown content prepended to every conversation. Use for rules, conventions, and domain knowledge that should always be present.
+- **`constraints`**: An array of hard rules. Each constraint is a MUST or MUST NOT statement that the agent should never violate.
+
+### `spec.tools`
+
+Controls which tools the agent can use within this role.
+
+- **`allowed`**: Whitelist of tool names. If specified, only these tools are available.
+- **`denied`**: Blacklist of tool names. Takes precedence over `allowed`.
+- **`skills`**: References to OSSA `kind: Skill` manifests that should be loaded.
+
+### `spec.hooks`
+
+Lifecycle hooks executed at specific points. Values are command strings or script references.
+
+- **`on_activate`**: Runs when the role is first activated in a session.
+- **`on_deactivate`**: Runs when switching away from this role.
+- **`pre_commit`**: Runs before git commit operations.
+- **`post_save`**: Runs after file save operations.
+
+### `spec.context`
+
+Injects additional context into the agent's working memory.
+
+- **`schemas`**: Paths to JSON Schema or OpenAPI specification files. The agent can reference these for type-correct code generation.
+- **`files`**: Specific files or globs to include in the agent's context window.
+- **`knowledge`**: Paths to knowledge base documents (markdown, text) that provide domain reference material.
+
+### `spec.protocols.mcp`
+
+MCP server connections available when this role is active.
+
+Each server entry requires:
+- **`name`**: Identifier for the MCP server.
+- **`transport`**: Either `stdio` (local process) or `sse` (HTTP Server-Sent Events).
+- **`command`** + **`args`**: For `stdio` transport, the command to spawn.
+- **`url`**: For `sse` transport, the endpoint URL.
+
+### `spec.extends`
+
+Enables role composition by inheriting from other roles.
+
+- **`role`**: Name of the parent role to inherit from.
+- **`override`**: If `true`, child fields replace parent fields. If `false` (default), child fields merge with parent fields (arrays are concatenated, objects are deep-merged).
+
+### `spec.activation`
+
+Defines conditions under which this role should automatically activate.
+
+- **`file_patterns`**: Glob patterns matched against open files. If any file matches, the role activates.
+- **`command`**: A slash command (e.g., `/role drupal`) that activates the role.
+- **`env`**: Environment variable conditions. All specified variables must match for activation.
+
+## Composition Rules
+
+When a role extends another:
+
+1. **`spec.role`**: Child replaces parent (no merge).
+2. **`spec.instructions.preamble`**: Child is appended after parent.
+3. **`spec.instructions.constraints`**: Arrays are concatenated (all constraints apply).
+4. **`spec.tools.allowed`**: Intersection of parent and child (child cannot grant tools the parent denies).
+5. **`spec.tools.denied`**: Union of parent and child (denials accumulate).
+6. **`spec.tools.skills`**: Arrays are concatenated.
+7. **`spec.hooks`**: Child hooks replace parent hooks for the same lifecycle event.
+8. **`spec.context`**: All context entries are merged (files, schemas, knowledge concatenated).
+9. **`spec.protocols.mcp.servers`**: Arrays are concatenated (all servers available).
+10. **`spec.activation`**: Child activation conditions replace parent.
+
+## Relationship to Other OSSA Kinds
+
+| Kind | Relationship to Role |
+|------|---------------------|
+| `Agent` | Roles are applied to agents. An agent can have multiple roles. |
+| `Skill` | Roles reference skills via `spec.tools.skills`. Skills provide capabilities; roles provide context. |
+| `Task` | Roles may influence how tasks are executed by setting constraints and tool access. |
+| `Workflow` | Roles can be assigned per workflow step to change agent behavior. |
+
+## Platform Mapping
+
+Roles map naturally to platform-specific configuration:
+
+| Role Field | Claude Code | Cursor | Codex CLI |
+|-----------|-------------|--------|-----------|
+| `spec.role` | CLAUDE.md system prompt | .cursorrules | instructions |
+| `spec.instructions.preamble` | CLAUDE.md content | .cursorrules content | --instructions |
+| `spec.tools.allowed` | Tool permissions | Tool config | --tools |
+| `spec.protocols.mcp` | .mcp.json servers | MCP config | MCP servers |
+| `spec.activation.file_patterns` | Glob triggers | File associations | --pattern |
+
+## Examples
+
+See `examples/roles/` for complete role manifests:
+
+- `drupal-developer.role.yaml` — Drupal module development
+- `security-auditor.role.yaml` — Security audit and compliance review
+- `platform-operator.role.yaml` — Full-stack platform operations with composition

package/dist/spec/layer4-economics/duadp-examples.json

@@ -0,0 +1,44 @@
+{
+  "records": [
+    {
+      "id": "did:web:bluefly.io:execution:profiles:fast-route",
+      "type": "ExecutionProfile",
+      "data": {
+        "profile_type": "fast-route",
+        "economics": {
+          "cost_ceiling_usd": 0.05,
+          "context_budget_tokens": 4096
+        },
+        "performance": {
+          "latency_target_ms": 500,
+          "priority": 90
+        }
+      }
+    },
+    {
+      "id": "did:web:bluefly.io:execution:profiles:deep-reason",
+      "type": "ExecutionProfile",
+      "data": {
+        "profile_type": "deep-reason",
+        "economics": {
+          "cost_ceiling_usd": 2.00,
+          "context_budget_tokens": 128000
+        },
+        "performance": {
+          "latency_target_ms": 30000,
+          "priority": 50
+        },
+        "reliability": {
+          "failure_semantics": "graceful-degradation",
+          "escalation_rules": [
+            {
+              "on_failure": "timeout",
+              "action": "fallback-profile",
+              "fallback_profile_id": "balanced-work"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

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

@@ -1414,6 +1414,20 @@
             "audit_required": { "type": "boolean", "default": false }
           },
           "additionalProperties": false
+        },
+        "sessions": {
+          "type": "object",
+          "description": "CAOE collaborative session capabilities for hypothesis broadcasting and conflict detection",
+          "properties": {
+            "sessionCapable": { "type": "boolean", "default": false },
+            "hypothesisEmission": { "type": "string", "enum": ["required", "optional", "disabled"], "default": "optional" },
+            "conflictBehavior": { "type": "string", "enum": ["block", "warn", "defer"], "default": "block" },
+            "alignmentGate": { "type": "string", "enum": ["human_approval", "auto_on_confidence", "peer_agent", "none"], "default": "human_approval" },
+            "autoLockConfidenceThreshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 },
+            "maxConcurrentHypotheses": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 },
+            "cognitiveFingerprint": { "type": "string" }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/dist/spec/v0.4/extensions/mcp/README.md

@@ -187,7 +187,7 @@ spec:
               - "-y"
               - "@modelcontextprotocol/server-postgres"
           env:
-            DATABASE_URL: "postgresql://user:pass@localhost:5432/db"
+            DATABASE_URL: "postgresql://user:${POSTGRES_PASSWORD}@localhost:5432/db"
           capabilities:
             tools:
               listChanged: false

package/dist/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/dist/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