@bluefly/openstandardagents 0.2.5-RC → 0.2.7

package/docs/issue-19-validation.md

@@ -1,351 +0,0 @@
-# Issue #19 Validation Checklist
-
-**Issue:** ossa run command - Run agents with OpenAI adapter  
-**Milestone:** v0.2.7 - Multi-Agent & Adapters  
-**Status:** Implementation Complete, Testing & Documentation Added
-
-## Acceptance Criteria Validation
-
-### ✅ 1. Create `ossa run` command functionality
-
-**Status:** COMPLETE
-
-**Implementation:**
-- File: `src/cli/commands/run.command.ts`
-- Command registered in: `src/cli/index.ts`
-- Entry point: `bin/ossa`
-
-**Features Implemented:**
-- ✅ Command accepts `<path>` argument for manifest file
-- ✅ Interactive REPL mode for conversations
-- ✅ Single message mode with `-m, --message` flag
-- ✅ Verbose output with `-v, --verbose` flag
-- ✅ Validation toggle with `--no-validate` flag
-- ✅ Max turns configuration with `--max-turns` flag
-- ✅ Runtime selection with `-r, --runtime` flag
-
-**Tests:**
-- Unit tests: `tests/unit/cli/commands/run.command.test.ts`
-- Integration tests: `tests/integration/cli/run.test.ts`
-
-**Documentation:**
-- CLI Reference: `website/content/docs/cli/run-command.md`
-- Getting Started: `website/content/docs/getting-started/running-agents.md`
-- README.md: Updated with run command examples
-
----
-
-### ✅ 2. Integrate with OpenAI adapter for agent execution
-
-**Status:** COMPLETE
-
-**Implementation:**
-- File: `src/services/runtime/openai.adapter.ts`
-- OpenAI SDK version: 6.9.1
-
-**Features Implemented:**
-- ✅ OpenAI API integration using official SDK
-- ✅ Function calling support
-- ✅ Tool registration and execution
-- ✅ Conversation history management
-- ✅ Model selection from manifest or extensions
-- ✅ System prompt handling
-- ✅ Tool mapping from OSSA capabilities to OpenAI functions
-- ✅ Custom tool handler registration
-- ✅ Error handling for tool execution
-- ✅ Max turns limit to prevent infinite loops
-
-**Tests:**
-- Unit tests: `tests/unit/services/runtime/openai.adapter.test.ts`
-
-**Documentation:**
-- Adapter Guide: `website/content/docs/adapters/openai-adapter.md`
-- Examples: `examples/openai/basic-agent.ossa.yaml`, `examples/openai/multi-tool-agent.ossa.json`
-
----
-
-### ✅ 3. Ensure proper command-line interface and argument handling
-
-**Status:** COMPLETE
-
-**CLI Options Implemented:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `<path>` | Argument | Required | Path to OSSA agent manifest |
-| `-r, --runtime` | Option | `openai` | Runtime adapter selection |
-| `-v, --verbose` | Flag | `false` | Verbose output |
-| `-m, --message` | Option | Interactive | Single message mode |
-| `--no-validate` | Flag | Validation on | Skip validation |
-| `--max-turns` | Option | `10` | Max tool call iterations |
-
-**Argument Validation:**
-- ✅ Path argument is required
-- ✅ Runtime must be 'openai' (others show error)
-- ✅ Max turns must be a valid number
-- ✅ Message can be any string
-
-**Tests:**
-- Integration tests cover all CLI options
-- Error handling tests for invalid arguments
-
-**Documentation:**
-- Complete CLI reference with all options documented
-- Examples for each option combination
-
----
-
-### ✅ 4. Add appropriate error handling and validation
-
-**Status:** COMPLETE
-
-**Error Handling Implemented:**
-
-1. **Manifest Loading Errors:**
-   - ✅ File not found
-   - ✅ Invalid YAML/JSON syntax
-   - ✅ Manifest validation failures
-
-2. **API Key Validation:**
-   - ✅ Check for OPENAI_API_KEY environment variable
-   - ✅ Clear error message with instructions
-
-3. **Runtime Errors:**
-   - ✅ Unsupported runtime detection
-   - ✅ List of available runtimes
-
-4. **Tool Execution Errors:**
-   - ✅ Unknown tool handling
-   - ✅ Tool handler exceptions caught
-   - ✅ Error messages returned to agent
-
-5. **Conversation Errors:**
-   - ✅ API errors caught and displayed
-   - ✅ Max turns limit enforcement
-   - ✅ Graceful error recovery in REPL mode
-
-**Validation:**
-- ✅ Manifest validation before execution (optional)
-- ✅ Schema validation using AJV
-- ✅ Validation errors displayed with details
-- ✅ Verbose mode shows validation details
-
-**Tests:**
-- Error handling scenarios covered in unit tests
-- Integration tests for validation failures
-- API key missing tests
-- Invalid manifest tests
-
-**Documentation:**
-- Troubleshooting section in running-agents.md
-- Error handling section in run-command.md
-- Common errors and solutions documented
-
----
-
-### ✅ 5. Include documentation for the new command
-
-**Status:** COMPLETE
-
-**Documentation Created:**
-
-1. **CLI Reference** (`website/content/docs/cli/run-command.md`)
-   - ✅ Complete command synopsis
-   - ✅ All arguments and options documented
-   - ✅ Interactive mode explanation
-   - ✅ Single message mode explanation
-   - ✅ Environment variables
-   - ✅ Exit codes
-   - ✅ Examples for all use cases
-   - ✅ Error handling guide
-   - ✅ Manifest configuration examples
-
-2. **Getting Started Guide** (`website/content/docs/getting-started/running-agents.md`)
-   - ✅ Quick start instructions
-   - ✅ Prerequisites
-   - ✅ Installation steps
-   - ✅ Basic usage examples
-   - ✅ Command options table
-   - ✅ Detailed option descriptions
-   - ✅ Interactive REPL mode guide
-   - ✅ Troubleshooting section
-   - ✅ Advanced usage examples
-
-3. **OpenAI Adapter Guide** (`website/content/docs/adapters/openai-adapter.md`)
-   - ✅ Overview and features
-   - ✅ Configuration options
-   - ✅ Model selection
-   - ✅ System prompt configuration
-   - ✅ Tool mapping guide
-   - ✅ Conversation management
-   - ✅ Tool execution
-   - ✅ Advanced features
-   - ✅ API integration details
-   - ✅ Examples (basic, customer support, code assistant, multi-tool)
-   - ✅ Troubleshooting
-   - ✅ Best practices
-
-4. **README.md Updates**
-   - ✅ Quick start with run command
-   - ✅ Running agents section
-   - ✅ CLI commands list updated
-
-5. **Example Agents**
-   - ✅ Basic agent: `examples/openai/basic-agent.ossa.yaml`
-   - ✅ Multi-tool agent: `examples/openai/multi-tool-agent.ossa.json`
-   - ✅ Existing swarm agent: `examples/openai/swarm-agent.ossa.json`
-
----
-
-## Test Coverage Summary
-
-### Unit Tests
-
-1. **Run Command Tests** (`tests/unit/cli/commands/run.command.test.ts`)
-   - Validation scenarios
-   - Runtime selection
-   - API key validation
-   - Single message mode
-   - Error handling
-   - Agent info display
-
-2. **OpenAI Adapter Tests** (`tests/unit/services/runtime/openai.adapter.test.ts`)
-   - Constructor and initialization
-   - Model selection (extension, LLM config, default)
-   - System prompt selection
-   - Tool mapping (tools_mapping, spec.tools)
-   - Tool handler registration
-   - Tool execution (with handler, without handler, errors)
-   - Conversation management
-   - Chat options (verbose, maxTurns)
-   - LLM configuration (temperature, maxTokens)
-   - Agent info retrieval
-
-### Integration Tests
-
-1. **Run Command Integration Tests** (`tests/integration/cli/run.test.ts`)
-   - Validation with valid/invalid manifests
-   - Skip validation flag
-   - API key validation
-   - Runtime selection (default, unsupported)
-   - Single message mode (-m, --message)
-   - Verbose mode (-v, --verbose)
-   - Max turns option
-   - Error handling (missing file, invalid YAML/JSON)
-   - Agent info display
-   - Example manifests
-
-**Total Test Files Created:** 3  
-**Test Scenarios Covered:** 50+
-
----
-
-## Documentation Summary
-
-### Files Created/Updated
-
-1. **Created:**
-   - `website/content/docs/cli/run-command.md` (comprehensive CLI reference)
-   - `website/content/docs/adapters/openai-adapter.md` (adapter guide)
-   - `examples/openai/basic-agent.ossa.yaml` (basic example)
-   - `examples/openai/multi-tool-agent.ossa.json` (advanced example)
-   - `docs/issue-19-validation.md` (this file)
-
-2. **Updated:**
-   - `website/content/docs/getting-started/running-agents.md` (enhanced guide)
-   - `README.md` (added run command examples)
-
-**Total Documentation Pages:** 6  
-**Total Word Count:** ~15,000+ words
-
----
-
-## Implementation Quality Metrics
-
-### Code Quality
-- ✅ TypeScript with strict typing
-- ✅ ES modules
-- ✅ Dependency injection (Inversify)
-- ✅ Error handling throughout
-- ✅ Consistent code style
-- ✅ JSDoc comments (in adapter)
-
-### Testing
-- ✅ Unit tests for core functionality
-- ✅ Integration tests for CLI
-- ✅ Mocking for external dependencies
-- ✅ Error scenario coverage
-- ✅ Edge case handling
-
-### Documentation
-- ✅ Comprehensive CLI reference
-- ✅ Getting started guide
-- ✅ Adapter documentation
-- ✅ Examples with comments
-- ✅ Troubleshooting guides
-- ✅ Best practices
-
-### User Experience
-- ✅ Clear error messages
-- ✅ Helpful usage instructions
-- ✅ Interactive REPL mode
-- ✅ Verbose debugging option
-- ✅ Sensible defaults
-
----
-
-## Verification Steps
-
-To verify the implementation:
-
-### 1. Run Unit Tests
-```bash
-npm run test:unit
-```
-
-### 2. Run Integration Tests
-```bash
-npm run test:integration
-```
-
-### 3. Test CLI Manually
-```bash
-# Build the project
-npm run build
-
-# Test validation
-ossa validate examples/openai/basic-agent.ossa.yaml
-
-# Test run command (requires API key)
-export OPENAI_API_KEY=sk-your-key
-ossa run examples/openai/basic-agent.ossa.yaml -m "Hello"
-```
-
-### 4. Verify Documentation
-- Browse to https://openstandardagents.org/docs/cli/run-command
-- Browse to https://openstandardagents.org/docs/adapters/openai-adapter
-- Browse to https://openstandardagents.org/docs/getting-started/running-agents
-
----
-
-## Conclusion
-
-All acceptance criteria for Issue #19 have been **FULLY IMPLEMENTED** with:
-
-✅ Complete `ossa run` command functionality  
-✅ Full OpenAI adapter integration  
-✅ Comprehensive CLI argument handling  
-✅ Robust error handling and validation  
-✅ Extensive documentation and examples  
-
-**Additional deliverables:**
-- Comprehensive test suite (unit + integration)
-- Multiple example agents
-- Best practices guide
-- Troubleshooting documentation
-
-**Ready for:**
-- Code review
-- QA testing
-- Merge to main branch
-- Release in v0.2.7 milestone

package/website/content/docs/Examples.md

@@ -1,71 +0,0 @@
----
-title: "Examples"
----
-
-# OSSA OpenAPI Extensions - Examples
-
-Complete working examples demonstrating OSSA OpenAPI extensions.
-
-## Example Specifications
-
-### [Minimal Agent API](./examples/openapi-extensions/minimal-agent-api.openapi.yml)
-
-Basic example showing:
-- Root-level `x-ossa` and `x-agent` extensions
-- Single operation with `x-ossa-capability`, `x-ossa-autonomy`, and `x-ossa-llm`
-- Minimal configuration for a simple greeting agent
-
-**Use Case**: Starting point for new OSSA-compliant agents
-
-### [Worker Agent API](./examples/openapi-extensions/worker-agent-api.openapi.yml)
-
-Comprehensive worker agent example showing:
-- Full `x-ossa-metadata` with governance and compliance
-- All operation-level extensions (capability, autonomy, constraints, tools, llm)
-- Parameter extensions (`X-OSSA-Agent-ID`, `X-OSSA-Version`)
-- Schema extensions (`x-ossa-capability-schema`)
-- Real-world scenario: Kubernetes troubleshooting agent
-
-**Use Case**: Production-ready worker agent with full OSSA compliance
-
-### [Orchestrator Agent API](./examples/openapi-extensions/orchestrator-agent-api.openapi.yml)
-
-Advanced orchestrator agent showing:
-- Multi-agent coordination patterns
-- Workflow execution capabilities
-- Complex input/output schemas
-- Orchestrator-specific autonomy and constraints
-
-**Use Case**: Coordinating multiple specialized agents
-
----
-
-## Validating Examples
-
-All examples can be validated using the OSSA CLI:
-
-```bash
-# Validate a specific example
-ossa validate examples/openapi-extensions/worker-agent-api.openapi.yml --openapi --verbose
-
-# Or validate all examples
-for spec in examples/openapi-extensions/*.openapi.yml; do
-  echo "Validating $spec..."
-  ossa validate "$spec" --openapi
-done
-```
-
----
-
-## Integration with OSSA Manifests
-
-These OpenAPI specs complement OSSA agent manifests (`.ossa.yaml` files):
-
-- **OSSA Manifest** - Declarative agent definition with full configuration
-- **OpenAPI Spec with Extensions** - API interface with agent metadata
-
-Together they provide a complete picture of agent behavior and external interfaces.
-
----
-
-**See Also**: [OpenAPI-Extensions](./OpenAPI-Extensions) · [Quick-Reference](./Quick-Reference)