@bluefly/openstandardagents 0.4.9 → 0.5.1

package/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/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/spec/v0.5/role.schema.json

@@ -0,0 +1,268 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.5/role.schema.json",
+  "title": "OSSA v0.5 Role Manifest Schema",
+  "description": "Open Standard for Software Agents (OSSA) v0.5 - Role manifest. Defines behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.) with instructions, tool sets, hooks, MCP connections, and activation conditions.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v[0-9]+(\\.[0-9]+)*(-[a-zA-Z0-9.]+)?$",
+      "description": "OSSA API version",
+      "examples": ["ossa/v0.5", "ossa/v1"]
+    },
+    "kind": {
+      "type": "string",
+      "const": "Role",
+      "description": "Resource type — must be Role"
+    },
+    "metadata": {
+      "$ref": "#/definitions/RoleMetadata"
+    },
+    "spec": {
+      "$ref": "#/definitions/RoleSpec"
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Platform-specific extensions",
+      "additionalProperties": true
+    }
+  },
+  "definitions": {
+    "RoleMetadata": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "DNS-style role name (lowercase, hyphens)",
+          "examples": ["drupal-developer", "security-auditor", "platform-operator"]
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$",
+          "description": "Semantic version",
+          "examples": ["1.0.0", "2.1.0-beta"]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Key-value labels for filtering and categorization"
+        },
+        "annotations": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Non-identifying metadata"
+        }
+      }
+    },
+    "RoleSpec": {
+      "type": "object",
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "System prompt / persona definition"
+        },
+        "instructions": {
+          "$ref": "#/definitions/RoleInstructions"
+        },
+        "tools": {
+          "$ref": "#/definitions/RoleTools"
+        },
+        "hooks": {
+          "$ref": "#/definitions/RoleHooks"
+        },
+        "context": {
+          "$ref": "#/definitions/RoleContext"
+        },
+        "protocols": {
+          "$ref": "#/definitions/RoleProtocols"
+        },
+        "extends": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleExtension" },
+          "description": "Role composition — inherit from other roles"
+        },
+        "activation": {
+          "$ref": "#/definitions/RoleActivation"
+        }
+      }
+    },
+    "RoleInstructions": {
+      "type": "object",
+      "properties": {
+        "preamble": {
+          "type": "string",
+          "description": "Markdown content prepended to every conversation"
+        },
+        "constraints": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Hard rules — MUST/MUST NOT statements"
+        }
+      }
+    },
+    "RoleTools": {
+      "type": "object",
+      "properties": {
+        "allowed": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Whitelist of allowed tool names"
+        },
+        "denied": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Blacklist of denied tool names (overrides allowed)"
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "References to OSSA Skill manifests"
+        }
+      }
+    },
+    "RoleHooks": {
+      "type": "object",
+      "properties": {
+        "on_activate": {
+          "type": "string",
+          "description": "Run when role is activated"
+        },
+        "on_deactivate": {
+          "type": "string",
+          "description": "Run when switching away from this role"
+        },
+        "pre_commit": {
+          "type": "string",
+          "description": "Run before git commits"
+        },
+        "post_save": {
+          "type": "string",
+          "description": "Run after file saves"
+        }
+      }
+    },
+    "RoleContext": {
+      "type": "object",
+      "properties": {
+        "schemas": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to JSON Schema or OpenAPI spec files"
+        },
+        "files": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleContextFile" },
+          "description": "Files to include in agent context"
+        },
+        "knowledge": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to knowledge base documents"
+        }
+      }
+    },
+    "RoleContextFile": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "File path or glob pattern"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of what this file provides"
+        }
+      }
+    },
+    "RoleProtocols": {
+      "type": "object",
+      "properties": {
+        "mcp": {
+          "$ref": "#/definitions/RoleMCPConfig"
+        }
+      }
+    },
+    "RoleMCPConfig": {
+      "type": "object",
+      "properties": {
+        "servers": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RoleMCPServer" },
+          "description": "MCP servers available when this role is active"
+        }
+      }
+    },
+    "RoleMCPServer": {
+      "type": "object",
+      "required": ["name", "transport"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Server identifier"
+        },
+        "transport": {
+          "type": "string",
+          "enum": ["stdio", "sse"],
+          "description": "Transport type"
+        },
+        "command": {
+          "type": "string",
+          "description": "Command to spawn (stdio transport)"
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Command arguments (stdio transport)"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Endpoint URL (SSE transport)"
+        }
+      }
+    },
+    "RoleExtension": {
+      "type": "object",
+      "required": ["role"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "Name of the parent role to inherit from"
+        },
+        "override": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, child fields replace parent fields; if false, they merge"
+        }
+      }
+    },
+    "RoleActivation": {
+      "type": "object",
+      "properties": {
+        "file_patterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns — activate when matching files are open"
+        },
+        "command": {
+          "type": "string",
+          "description": "CLI command to activate (e.g., /role drupal)"
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Environment variable conditions (all must match)"
+        }
+      }
+    }
+  }
+}