@bluefly/openstandardagents 0.5.3 → 0.5.5

package/README.md

@@ -1,43 +1,129 @@
 # Open Standard for Software Agents (OSSA)
 
+OSSA is an open standard for defining, validating, discovering, and governing software agents.
+
+OSSA is not a framework. It is a contract layer: schema, identity, capabilities, policy bindings, discovery metadata, and validation rules that allow agents to be portable across runtimes and organizations.
+
+> Development happens on [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) (source of truth).
+> [Source](https://gitlab.com/blueflyio/ossa/openstandardagents) | [Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues) | [npm](https://www.npmjs.com/package/@bluefly/openstandardagents)
+
+## Why OSSA Exists
+
+Agent systems are fragmenting across IDEs, model providers, MCP servers, workflow engines, Drupal, GitLab, Kubernetes, and private enterprise platforms.
+
+OSSA provides a stable contract for agent identity, manifests, tool declarations, capability boundaries, governance metadata, runtime interoperability, discovery, validation, and auditability.
+
+Without a contract layer, every integration is bespoke. With OSSA, one manifest describes an agent and any conforming runtime can consume it.
+
+## Core Analogy
+
 **OpenAPI : APIs :: OSSA : Agents**
 
-`@bluefly/openstandardagents` is a **spec-first** npm package: JSON Schema for agent manifests, a minimal invocation OpenAPI contract, a validator, and a small CLI. It is not a deployment framework, mesh runtime, or IDE plugin host.
+OpenAPI does not implement your API. It describes it.
+OSSA does not implement your agent. It describes it.
+
+## Package
 
-| Resource | Location |
-|----------|----------|
-| Specification (v0.5) | [`spec/v0.5/`](spec/v0.5/) |
-| Discovery document | [`.well-known/ossa.json`](.well-known/ossa.json) |
-| Migration from pre-recovery tree | [`MIGRATION.md`](MIGRATION.md) |
-| Operator detail | [`docs/spec.md`](docs/spec.md) |
+**npm:** `@bluefly/openstandardagents`
 
-Development: [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) (source of truth). Issues and MRs belong there.
+Current stable release: `0.5.1`
+Prepared release: `0.5.2`
 
-## Install
+> **Note:** `0.5.3` was accidentally published during recovery and is deprecated. Do not use it.
 
 ```bash
-npm install @bluefly/openstandardagents@0.5.2
+npm install @bluefly/openstandardagents@0.5.5
 ```
 
 Requires Node.js 20+.
 
 ## CLI
 
-After clone, build workspace packages then use the repo script (avoids conflicting global `ossa` shims):
+```bash
+npx ossa validate ./agent.ossa.yaml
+npx ossa validate-spec
+npx ossa discover https://example.com
+npx ossa resolve-did did:web:example.com:agent:demo
+npx ossa lint-openapi
+```
+
+Exit code `0` means valid. Non-zero prints JSON-pointer paths and error messages.
+
+From a repo clone (avoids conflicting global shims):
 
 ```bash
 pnpm install
 pnpm build
 pnpm run ossa validate path/to/agent.ossa.yaml
-pnpm run ossa validate-spec
-pnpm run ossa resolve-did did:web:example.com:agent:demo
-pnpm run ossa discover https://openstandardagents.org
-pnpm run ossa lint-openapi
 ```
 
-Exit code `0` prints `valid` for manifest validation; non-zero prints JSON-pointer paths and messages.
+## What This Package Contains
+
+- JSON Schemas for OSSA v0.5 manifests (agent, workflow, registry, policy-binding)
+- Reference OpenAPI contracts (invocation, compliance-engine)
+- Validation utilities (programmatic and CLI)
+- CLI entrypoint (`ossa`)
+- Reference agent manifests
+- Well-known discovery document (`.well-known/ossa.json`)
+
+## What This Package Does Not Contain
+
+- Agent runtime
+- Orchestration engine
+- MCP server implementation
+- Deployment controller
+- Drupal module
+- GitLab automation
+- Policy decision point
+
+Those belong in adjacent projects (see Project Ecosystem below).
+
+## OSSA v0.5 Concepts
 
-## Programmatic validation
+**Agent Manifest** — Defines an agent's identity, role, tools, capabilities, governance metadata, and interoperability surfaces.
+
+**Role** — A behavioral and operational profile used by an agent, IDE, runtime, or workflow.
+
+**Tool** — A callable capability declared by the manifest and enforced by the runtime or policy layer.
+
+**Workflow** — A deterministic or semi-deterministic process composed from agents, tools, events, or external systems.
+
+**Registry** — A discoverable index of agent manifests and related metadata.
+
+**Policy Binding** — A link between an agent/action/resource and an external policy authority such as Cedar or ContractPlane.
+
+## Minimal Manifest Example
+
+```yaml
+apiVersion: ossa/v0.5
+kind: Agent
+metadata:
+  name: accessibility-reviewer
+  namespace: blueflyio
+  version: 1.0.0
+  uuid: 7e3f4b8d-2c91-4a6e-b015-9f8d3e2c7a64
+spec:
+  role: accessibility-reviewer
+  description: Reviews content and rendered pages for accessibility issues.
+  tools:
+    - name: drupal_render_api
+      type: mcp
+    - name: axe_core_scanner
+      type: external
+  capabilities:
+    - name: scan_page_accessibility
+    - name: generate_remediation_plan
+  governance:
+    cedar_policy_pack: accessibility-reviewer-v1
+    trust_tier: T2
+    evidence_required: true
+  discovery:
+    duadp: true
+```
+
+## Validation
+
+### Programmatic
 
 ```typescript
 import { validateManifestFile } from '@bluefly/openstandardagents';
@@ -45,30 +131,131 @@ import { validateManifestFile } from '@bluefly/openstandardagents';
 const result = await validateManifestFile('agent.ossa.yaml');
 if (!result.valid) {
   console.error(result.errors);
+  process.exit(1);
 }
 ```
 
-## What belongs elsewhere
+### CLI
+
+```bash
+ossa validate ./agent.ossa.yaml
+```
+
+## Exports
+
+| Export | Purpose |
+|--------|---------|
+| `@bluefly/openstandardagents` | Validator entrypoint |
+| `@bluefly/openstandardagents/schema` | v0.5 agent schema |
+| `@bluefly/openstandardagents/schema/v0.5` | Explicit v0.5 agent schema |
+| `@bluefly/openstandardagents/schema/workflow` | Workflow schema |
+| `@bluefly/openstandardagents/schema/registry` | Registry schema |
+| `@bluefly/openstandardagents/schema/policy-binding` | Policy binding schema |
+| `@bluefly/openstandardagents/openapi/invocation` | Invocation OpenAPI contract |
+| `@bluefly/openstandardagents/well-known` | OSSA well-known discovery document |
+| `@bluefly/openstandardagents/validation` | Validation utilities (alias) |
+
+## Project Ecosystem
+
+| Project | Role |
+|---------|------|
+| [openstandardagents](https://gitlab.com/blueflyio/ossa/openstandardagents) | OSSA schemas, CLI, validator, reference contracts |
+| [duadp](https://gitlab.com/blueflyio/duadp/duadp) | Federated discovery and agent registry resolution |
+| [agents](https://gitlab.com/blueflyio/agentictools/agents) | Canonical Bluefly agent manifests, including @blu |
+| [skills](https://gitlab.com/blueflyio/agentictools/skills) | Reusable skill packages referenced by agents |
+| [compliance-engine](https://gitlab.com/blueflyio/agent-platform/services/compliance-engine) | Cedar policy evaluation, evidence, and OSSA validation API |
+| [cedar-policies](https://gitlab.com/blueflyio/cedar-policies) | Cedar policy source (product IP) |
+| [ai_agents_ossa](https://gitlab.com/blueflyio/agent-platform/drupal/ai_agents_ossa) | Drupal bridge between OSSA manifests and AI Agents |
+| [api_normalization](https://gitlab.com/blueflyio/agent-platform/drupal/api_normalization) | API/OpenAPI normalization layer |
+| [kb_cache](https://gitlab.com/blueflyio/agent-platform/drupal/kb_cache) | Contextual memory and retrieval engine |
+| [ContextControl.ai](https://gitlab.com/blueflyio/contextcontrol.ai) | Governed Drupal-based context/control plane |
+| [blu-cli](https://gitlab.com/blueflyio/blu/blu-cli) | Governed Bluefly operator CLI |
+| [context-cli](https://gitlab.com/blueflyio/contextcontrol.ai/context-cli) | ContextControl/knowledge workflow CLI |
+| [gitlab_components](https://gitlab.com/blueflyio/gitlab_components) | Reusable CI/CD pipeline components |
+| [ossa-studio](https://gitlab.com/blueflyio/ossa/lab/ossa-studio) | Visual/modeling surface for OSSA authoring |
 
-| Concern | Owner |
-|---------|--------|
-| Agent manifests (Blu, platform agents) | [`WORKING_DEMOs/agents`](https://gitlab.com/blueflyio/agents) |
-| Cedar policy source | `WORKING_DEMOs/cedar-policies` |
-| OSSA validate + Cedar (HTTP) | compliance-engine (`POST /api/v1/compliance/ossa/validate`) |
-| Export to K8s, Kagent, Drupal | `ossa-deploy`, `agent-buildkit`, `platform-agents` |
-| DUADP discovery | `@bluefly/duadp` |
+## Relationship to DUADP
 
-## CI (this repository)
+DUADP handles discovery. OSSA defines what is discovered.
+
+OSSA answers: What is this agent? What can it do? What tools does it declare? What policy bindings apply? What schema validates it?
+
+DUADP answers: Where is the agent card? How is it resolved? How is it revoked? How is it discovered across organizations?
+
+## Relationship to ContractPlane and Cedar
+
+OSSA declares governance metadata and policy bindings. It does not evaluate policy.
+
+ContractPlane and Cedar are policy/evidence enforcement layers that consume OSSA manifests and evaluate actions before runtime execution. Cedar policies are authored in `cedar-policies` and evaluated by `compliance-engine`.
+
+## Relationship to Drupal
+
+Drupal is one implementation surface for OSSA-governed agents. OSSA remains runtime-agnostic. Drupal is an implementation target, not a dependency of the standard.
+
+Relevant Drupal modules: `ai`, `ai_agents`, `ai_agents_ossa`, `tool`, `mcp`, `orchestration`, `eca`, `agui`, `api_normalization`, `ai_context`, `kb_cache`.
+
+## Why OSSA + DUADP
+
+AI agents need the same foundational infrastructure the internet has: identity, discovery, and governance.
+
+```
+Identity   (OSSA)  — Agent DID, signed manifests, Cedar policy bindings
+Discovery  (DUADP) — Federated DNS + WebFinger, gossip, trust-tier gating
+Execution  (yours) — Kubernetes, Claude, LangChain, Drupal, or any runtime
+```
+
+OSSA defines the agent. DUADP discovers it. Your runtime executes it.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm validate
+pnpm gen:check
+pnpm publint
+```
+
+Full CI-equivalent gate:
 
 ```bash
 pnpm ci:validate
 ```
 
-Runs install, build, typecheck, vitest conformance, `validate:schema`, and `validate:openapi`. All jobs are fail-closed.
+Runs install, build, typecheck, vitest conformance, schema validation, OpenAPI validation, generated-code checks, and package dry-run. All jobs are fail-closed.
+
+## Conformance Targets
+
+Tests validate the canonical platform agent at `WORKING_DEMOs/agents/agents/@blu/agent.ossa.yaml` when `OSSA_AGENTS_ROOT` points at that repo (default relative path from this checkout). Toy example directories are not shipped in this package.
+
+## Release Policy
+
+- Release branches are protected.
+- Release artifacts must pass build, typecheck, tests, schema validation, OpenAPI validation, generated-code checks, and package dry-run.
+- npm versions are immutable after publish.
+- Package contents must be allowlisted through `files`.
+- Do not publish from a dirty working tree.
+- Do not publish from a generated temporary tree unless the package identity and tarball contents are verified.
+
+## npm State
 
-## Conformance targets
+`0.5.1` is the current stable release. `0.5.2` is prepared and in pre-release validation.
 
-Tests validate the **canonical platform agent** at `WORKING_DEMOs/agents/agents/@blu/agent.ossa.yaml` when `OSSA_AGENTS_ROOT` points at that repo (default relative path from this checkout). Toy example directories are not shipped in this package.
+`0.5.3` was accidentally published during recovery and is **deprecated**. Do not use it.
+
+## Contributing
+
+Use GitLab issues and merge requests against the source of truth:
+
+https://gitlab.com/blueflyio/ossa/openstandardagents
+
+Before submitting:
+
+```bash
+pnpm ci:validate
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluefly/openstandardagents",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "OSSA - Open Standard for Software Agents. Spec-first schemas, validator, and CLI.",
   "bin": {
     "ossa": "packages/cli/dist/cli.js"