@bluefly/openstandardagents 0.4.9 → 0.5.1

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