@bluefly/openstandardagents 0.5.0 → 0.5.1

package/dist/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/dist/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"
+    }
+  }
+}

package/dist/spec/v0.5/extensions/economics/replay-packet.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.5.0/replay-packet.schema.json",
+  "title": "OSSA v0.5.0 Replay Packet Schema",
+  "description": "ReplayPacket is a portable execution artifact for audit, governance, and benchmarking. It enables high-fidelity reproduction of agent reasoning.",
+  "type": "object",
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v0\\.5.*$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "ReplayPacket"
+    },
+    "metadata": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": [
+        "execution_id",
+        "events"
+      ],
+      "properties": {
+        "execution_id": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "profile_id": {
+          "type": "string",
+          "description": "The ExecutionProfile used during this execution."
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "timestamp",
+              "type"
+            ],
+            "properties": {
+              "timestamp": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "input",
+                  "output",
+                  "tool_call",
+                  "tool_result",
+                  "state_change",
+                  "metric",
+                  "human_intervention"
+                ]
+              },
+              "data": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "metrics": {
+          "type": "object",
+          "properties": {
+            "duration_ms": {
+              "type": "integer"
+            },
+            "input_tokens": {
+              "type": "integer"
+            },
+            "output_tokens": {
+              "type": "integer"
+            },
+            "total_cost_usd": {
+              "type": "number"
+            },
+            "efficiency_score": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        },
+        "provenance": {
+          "type": "object",
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "DID or Public Key of the signing entity."
+            },
+            "signature": {
+              "type": "string"
+            },
+            "hash": {
+              "type": "string",
+              "description": "Content-addressable hash of the packet."
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

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

package/dist/spec/v0.5/memory-hierarchy.yaml

@@ -0,0 +1,120 @@
+# OSSA Memory Hierarchy Contracts v0.5.0
+# ============================================================================
+# Document: memory tier conventions, directory structure, naming contracts.
+# These are contracts only — HierarchicalMemoryResolver implementation deferred
+# to P7 (agent-brain service, brain.bluefly.internal:6333).
+# ============================================================================
+#
+# Per COMPLETION_REPORT_AGENT_BUILDER.md Phase 5 (contracts-only). Resolver
+# deferred — implement ONLY after P1–P4 are green and passing CI.
+
+memory_hierarchy:
+  apiVersion: "ossa/v0.5.0"
+  kind: MemoryContracts
+  description: |
+    Three-tier memory system for OSSA agents. Each tier is isolated by scope:
+    global (platform-wide shared state), domain (capability-scoped working
+    memory), and agent (per-agent private context). Tiers merge at runtime
+    via the HierarchicalMemoryResolver — lower tiers cannot overwrite higher.
+
+  tiers:
+    global:
+      description: "Platform-wide shared memory. Read by all agents. Written only by operators."
+      directory: ".agents-workspace/memory/"
+      naming_scheme: "global.<collection>"
+      examples:
+        - "global.policies"
+        - "global.cedar-rules"
+        - "global.compliance-baseline"
+      gitignore_rules:
+        - ".agents-workspace/memory/*.db"
+        - ".agents-workspace/memory/*.sqlite"
+        - ".agents-workspace/memory/.cache/"
+      commit_rule: "Schemas and seed data MUST be committed. Cache and runtime state MUST NOT."
+
+    domain:
+      description: "Capability-scoped working memory. Shared within a domain (e.g. gitlab, drupal, security)."
+      directory: ".agents/workspace/memory/"
+      naming_scheme: "<domain>.<collection>"
+      examples:
+        - "gitlab.mr-context"
+        - "drupal.module-catalog"
+        - "security.vuln-signatures"
+      gitignore_rules:
+        - ".agents/workspace/memory/*.db"
+        - ".agents/workspace/memory/*.sqlite"
+        - ".agents/workspace/memory/.cache/"
+      commit_rule: "Domain-scoped seed data committed. Runtime embeddings excluded."
+
+    agent:
+      description: "Per-agent private context. Not shared across agents. Scoped to agent lifecycle."
+      directory: ".agents/agents/<agent-name>/memory/"
+      naming_scheme: "<domain>.<agent>.<collection>"
+      examples:
+        - "gitlab.mr-reviewer.recent-reviews"
+        - "drupal.module-generator.scaffold-history"
+        - "security.scanner.false-positive-index"
+      gitignore_rules:
+        - ".agents/agents/*/memory/*.db"
+        - ".agents/agents/*/memory/*.sqlite"
+        - ".agents/agents/*/memory/.cache/"
+        - ".agents/agents/*/memory/embeddings/"
+      commit_rule: "Only seed data committed. All runtime state excluded."
+
+# =============================================================================
+# Canonical .gitignore block — copy into consuming repos
+# =============================================================================
+gitignore_block: |
+  # OSSA Memory Hierarchy — runtime state excluded, schemas committed
+  .agents-workspace/memory/*.db
+  .agents-workspace/memory/*.sqlite
+  .agents-workspace/memory/.cache/
+  .agents/workspace/memory/*.db
+  .agents/workspace/memory/*.sqlite
+  .agents/workspace/memory/.cache/
+  .agents/agents/*/memory/*.db
+  .agents/agents/*/memory/*.sqlite
+  .agents/agents/*/memory/.cache/
+  .agents/agents/*/memory/embeddings/
+
+# =============================================================================
+# Resolver contract (deferred P7 implementation in agent-brain)
+# =============================================================================
+resolver:
+  service: "agent-brain"
+  endpoint: "http://brain.bluefly.internal:6333"
+  protocol: "REST"
+  merge_order:
+    - "global"   # lowest precedence (base layer)
+    - "domain"   # mid layer
+    - "agent"    # highest precedence (wins on conflict)
+  implementation: "DEFERRED — implement after P1-P4 green"
+  interface:
+    resolve:
+      method: "GET"
+      path: "/api/v1/memory/{collection}"
+      description: "Merge tiers and return resolved context for a named collection."
+    index:
+      method: "POST"
+      path: "/api/v1/memory/{tier}/{collection}/index"
+      description: "Vector-index a memory collection for semantic retrieval."
+    promote:
+      method: "POST"
+      path: "/api/v1/memory/{collection}/promote"
+      description: "Promote agent memory to domain tier (requires operator approval)."
+
+# =============================================================================
+# ossa scaffold extension — directory scaffold
+# =============================================================================
+scaffold:
+  description: |
+    `ossa scaffold` MUST emit memory/ directories when generating a new agent workspace.
+    Add to ossa scaffold templates when implementing CLI extension (P5 CLI work).
+  directories:
+    - ".agents-workspace/memory/"
+    - ".agents/workspace/memory/"
+    # Per-agent dirs created by ossa scaffold --agent <name>:
+    # .agents/agents/<name>/memory/
+  seed_files:
+    global_readme: ".agents-workspace/memory/README.md"
+    domain_readme: ".agents/workspace/memory/README.md"

package/dist/spec/v1/agent-card.schema.json

@@ -0,0 +1,254 @@
+{
+  "$id": "https://ossa.dev/spec/v1/agent-card.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agent Card v1.0",
+  "description": "Machine-readable agent passport enabling auto-discovery, auth negotiation, capability verification, and A2A protocol compatibility.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "humanReadableId",
+    "agentVersion",
+    "name",
+    "description",
+    "url",
+    "capabilities",
+    "authSchemes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Version of the Agent Card schema."
+    },
+    "humanReadableId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$",
+      "description": "Unique namespace/agent identifier in 'org/agent-name' format.",
+      "examples": ["acme/weather-reporter", "blueflyio/code-review-agent"]
+    },
+    "agentVersion": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+      "description": "Semantic version (MAJOR.MINOR.PATCH) of the agent software.",
+      "examples": ["1.0.0", "2.1.0-beta.1"]
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 150,
+      "description": "Human-readable display name."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Clear description of the agent's purpose and capabilities."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Primary A2A endpoint URL. MUST use HTTPS except for localhost.",
+      "examples": ["https://api.my-agent.example.com/a2a"]
+    },
+    "provider": {
+      "$ref": "#/$defs/Provider"
+    },
+    "capabilities": {
+      "$ref": "#/$defs/Capabilities"
+    },
+    "authSchemes": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Authentication schemes supported. At least one is required.",
+      "items": {
+        "$ref": "#/$defs/AuthScheme"
+      }
+    },
+    "skills": {
+      "type": "array",
+      "description": "Discrete operations the agent can perform.",
+      "items": {
+        "$ref": "#/$defs/Skill"
+      }
+    },
+    "tags": {
+      "type": "array",
+      "description": "Searchable discovery keywords.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "privacyPolicyUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the agent's privacy policy."
+    },
+    "termsOfServiceUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the agent's terms of service."
+    },
+    "iconUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the agent's icon image."
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last modification to this card."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Provider": {
+      "type": "object",
+      "required": ["name"],
+      "description": "Organization or individual operating this agent.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Display name of the provider."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Provider's homepage URL."
+        },
+        "support_contact": {
+          "type": "string",
+          "description": "Support contact (email, URL, or mailto: URI)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Capabilities": {
+      "type": "object",
+      "required": ["a2aVersion"],
+      "description": "Protocol capabilities for this agent.",
+      "properties": {
+        "a2aVersion": {
+          "type": "string",
+          "description": "A2A protocol version supported.",
+          "examples": ["1.0"]
+        },
+        "mcpVersion": {
+          "type": "string",
+          "description": "MCP protocol version supported, if any.",
+          "examples": ["0.6"]
+        },
+        "supportedMessageParts": {
+          "type": "array",
+          "description": "Message part types this agent can consume/produce.",
+          "items": {
+            "type": "string",
+            "enum": ["text", "file", "data", "image", "audio", "video"]
+          }
+        },
+        "supportsPushNotifications": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the agent supports async push notifications."
+        },
+        "teeDetails": {
+          "$ref": "#/$defs/TeeDetails"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TeeDetails": {
+      "type": "object",
+      "required": ["type"],
+      "description": "Trusted Execution Environment attestation details.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "TEE technology type.",
+          "examples": ["Intel SGX", "AMD SEV", "AWS Nitro"]
+        },
+        "attestationEndpoint": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the TEE remote attestation endpoint."
+        },
+        "publicKey": {
+          "type": "string",
+          "description": "PEM-encoded public key of the enclave."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable explanation of what the TEE protects."
+        }
+      },
+      "additionalProperties": false
+    },
+    "AuthScheme": {
+      "type": "object",
+      "required": ["scheme"],
+      "description": "A single authentication method supported by the agent.",
+      "properties": {
+        "scheme": {
+          "type": "string",
+          "enum": ["apiKey", "oauth2", "bearer", "none"],
+          "description": "Authentication scheme identifier."
+        },
+        "description": {
+          "type": "string",
+          "description": "How to obtain and use credentials for this scheme."
+        },
+        "tokenUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "OAuth2 token endpoint. Required when scheme is 'oauth2'."
+        },
+        "scopes": {
+          "type": "array",
+          "description": "OAuth2 scopes required (scheme: oauth2 only).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "service_identifier": {
+          "type": "string",
+          "description": "Stable key for credential managers (e.g., 'acme-weather-api')."
+        }
+      },
+      "if": {
+        "properties": { "scheme": { "const": "oauth2" } }
+      },
+      "then": {
+        "required": ["tokenUrl"]
+      },
+      "additionalProperties": false
+    },
+    "Skill": {
+      "type": "object",
+      "required": ["id", "name", "description"],
+      "description": "A discrete callable operation the agent can perform.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "description": "Stable machine-readable skill identifier, unique within the agent."
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable display name."
+        },
+        "description": {
+          "type": "string",
+          "description": "Purpose and behaviour of this skill."
+        },
+        "input_schema": {
+          "type": "object",
+          "description": "JSON Schema describing the expected input payload.",
+          "additionalProperties": true
+        },
+        "output_schema": {
+          "type": "object",
+          "description": "JSON Schema describing the response payload structure.",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}