From 607de5eb7df7d69689c2a89b02faf0269525ed2e Mon Sep 17 00:00:00 2001 From: John Doe Date: Tue, 31 Mar 2026 21:14:43 -0400 Subject: [PATCH] chore: Add CI/CD workflows, CODEOWNERS, and documentation templates --- .github/workflows/ci.yml | 146 +++++++++++++++++ .github/workflows/release.yml | 173 ++++++++++++++++++++ CODEOWNERS | 52 ++++++ CONTRIBUTING.md | 296 ++++++++++++++++++++++++++++++++++ README.md | 252 +++++++++++++++++++++++++++++ 5 files changed, 919 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 CODEOWNERS create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..d8a3967 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,146 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run ESLint + run: npm run lint + + - name: Run Prettier check + run: npm run format:check + + test: + name: Test + runs-on: ubuntu-latest + services: + postgres: + image: postgres:15 + env: + POSTGRES_USER: test + POSTGRES_PASSWORD: test + POSTGRES_DB: test + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + redis: + image: redis:7 + ports: + - 6379:6379 + options: >- + --health-cmd "redis-cli ping" + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm run test + env: + POSTGRES_HOST: localhost + POSTGRES_PORT: 5432 + POSTGRES_USER: test + POSTGRES_PASSWORD: test + POSTGRES_DB: test + REDIS_HOST: localhost + REDIS_PORT: 6379 + + - name: Upload coverage + uses: codecov/codecov-action@v3 + if: always() + with: + files: ./coverage/coverage-final.json + fail_ci_if_error: false + + build: + name: Build + runs-on: ubuntu-latest + needs: [lint, typecheck, test] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: build + path: dist/ + retention-days: 7 + + security: + name: Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run npm audit + run: npm audit --audit-level=moderate + continue-on-error: true + + - name: Run Snyk + uses: snyk/actions/node@master + continue-on-error: true + env: + SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..1d4d2d9 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,173 @@ +name: Release + +on: + push: + tags: + - 'v*' + - '*/v*' + +permissions: + contents: write + packages: write + +jobs: + release: + name: Create Release + runs-on: ubuntu-latest + outputs: + version: ${{ steps.get_version.outputs.version }} + component: ${{ steps.get_version.outputs.component }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Get version + id: get_version + run: | + TAG=${GITHUB_REF#refs/tags/} + VERSION=${TAG##*/v} + COMPONENT=${TAG%/*} + if [ "$COMPONENT" = "$TAG" ]; then + COMPONENT="" + fi + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "component=$COMPONENT" >> $GITHUB_OUTPUT + echo "Version: $VERSION" + echo "Component: $COMPONENT" + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Generate changelog + id: changelog + run: | + PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "") + if [ -z "$PREVIOUS_TAG" ]; then + CHANGELOG=$(git log --pretty=format:"- %s (%h)" HEAD) + else + CHANGELOG=$(git log --pretty=format:"- %s (%h)" $PREVIOUS_TAG..HEAD) + fi + echo "changelog<> $GITHUB_OUTPUT + echo "$CHANGELOG" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + - name: Create GitHub Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ steps.get_version.outputs.version }} + body: | + ## Changes + + ${{ steps.changelog.outputs.changelog }} + + ## Installation + + ```bash + npm install @heretek/openclaw-${{ steps.get_version.outputs.component }}@${{ steps.get_version.outputs.version }} + ``` + draft: false + prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'alpha') }} + + publish-npm: + name: Publish to npm + runs-on: ubuntu-latest + needs: release + if: ${{ !contains(needs.release.outputs.component, 'deploy') && !contains(needs.release.outputs.component, 'docs') }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + registry-url: 'https://registry.npmjs.org' + + - name: Install dependencies + run: npm ci + + - name: Update version + run: npm version ${{ needs.release.outputs.version }} --no-git-tag-version + + - name: Build + run: npm run build + + - name: Publish to npm + run: npm publish --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Create npm release notes + run: | + echo "Published @heretek/openclaw-${{ needs.release.outputs.component }}@${{ needs.release.outputs.version }} to npm" + + publish-docker: + name: Publish to Docker Hub + runs-on: ubuntu-latest + needs: release + if: ${{ needs.release.outputs.component == 'core' || needs.release.outputs.component == '' }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: . + push: true + tags: | + heretek/openclaw:${{ needs.release.outputs.version }} + heretek/openclaw:latest + platforms: linux/amd64,linux/arm64 + cache-from: type=registry,ref=heretek/openclaw:buildcache + cache-to: type=registry,ref=heretek/openclaw:buildcache,mode=max + + notify: + name: Notify + runs-on: ubuntu-latest + needs: [release, publish-npm, publish-docker] + if: always() + steps: + - name: Notify Slack + uses: slackapi/slack-github-action@v1 + if: ${{ needs.release.result == 'success' }} + with: + payload: | + { + "text": "πŸš€ Released: ${{ github.repository }} v${{ needs.release.outputs.version }}", + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "πŸš€ *New Release*\n*${{ github.repository }}* v${{ needs.release.outputs.version }}\n${{ github.event.release.html_url }}" + } + } + ] + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..bb9fe16 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,52 @@ +# Heretek OpenClaw CODEOWNERS +# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners + +# This file defines who is responsible for code reviews in this repository. +# Each line specifies a path pattern and the users/groups responsible for it. + +# Format: +# ... + +# Default owners for the entire repository +* @heretek/core-team + +# Core team has ownership of all code +/src/ @heretek/core-team + +# Agent-specific ownership +/src/agents/ @heretek/core-team +/src/agents/steward/ @heretek/core-team +/src/agents/explorer/ @heretek/core-team +/src/agents/sentinel/ @heretek/core-team + +# Skills ownership +/src/skills/ @heretek/core-team +/src/skills/triad-* @heretek/core-team +/src/skills/memory-* @heretek/core-team + +# Plugin ownership +/plugins/ @heretek/core-team +/plugins/consciousness/ @heretek/core-team +/plugins/liberation/ @heretek/core-team + +# Test ownership +/tests/ @heretek/core-team +/tests/unit/ @heretek/core-team +/tests/integration/ @heretek/core-team +/tests/e2e/ @heretek/core-team + +# Configuration ownership +/openclaw.json @heretek/core-team +/package.json @heretek/core-team + +# Documentation ownership +/docs/ @heretek/core-team +/README.md @heretek/core-team + +# Infrastructure ownership +/Dockerfile @heretek/core-team +/docker-compose.yml @heretek/core-team +/deploy/ @heretek/core-team + +# CI/CD ownership +.github/workflows/ @heretek/core-team diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2e2a88d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,296 @@ +# Contributing to Heretek OpenClaw + +Thank you for your interest in contributing to Heretek OpenClaw! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Pull Requests](#pull-requests) +- [Testing](#testing) +- [Code Style](#code-style) +- [Commit Messages](#commit-messages) + +## Code of Conduct + +- Be respectful and inclusive +- Focus on constructive feedback +- Welcome newcomers and help them learn +- Keep discussions on topic + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally + ```bash + git clone https://github.com/your-username/heretek-openclaw-core.git + cd heretek-openclaw-core + ``` +3. **Add upstream remote** + ```bash + git remote add upstream https://github.com/heretek/heretek-openclaw-core.git + ``` +4. **Install dependencies** + ```bash + npm install + ``` + +## Development Setup + +### Prerequisites + +- Node.js 20+ +- npm 9+ +- Git +- Docker (for integration tests) + +### Environment Setup + +```bash +# Copy environment template +cp .env.example .env + +# Edit with your settings +nano .env +``` + +### Running Locally + +```bash +# Development mode +npm run dev + +# Run tests +npm test + +# Lint code +npm run lint +``` + +## Making Changes + +### Branch Naming + +Use descriptive branch names: + +``` +feature/add-new-skill +fix/gateway-memory-leak +docs/update-api-reference +refactor/improve-error-handling +``` + +### Making Commits + +1. **Create a branch** from `main` + ```bash + git checkout -b feature/your-feature + ``` + +2. **Make focused commits** + - Each commit should do one thing + - Write clear commit messages + - Test before committing + +3. **Keep your branch updated** + ```bash + git fetch upstream + git rebase upstream/main + ``` + +## Pull Requests + +### Before Submitting + +- [ ] Tests pass locally +- [ ] Code is linted +- [ ] Documentation is updated +- [ ] Changes are tested + +### PR Description + +Use the PR template and include: + +- **What** changes are being made +- **Why** the changes are needed +- **How** the changes were tested +- **Related issues** (if any) + +### Review Process + +1. **Automated checks** must pass +2. **Code review** by maintainers +3. **Address feedback** promptly +4. **Squash commits** if requested + +## Testing + +### Running Tests + +```bash +# All tests +npm test + +# Unit tests only +npm run test:unit + +# Integration tests only +npm run test:integration + +# With coverage +npm run test:coverage +``` + +### Writing Tests + +- Write tests for new features +- Update tests when fixing bugs +- Aim for meaningful coverage +- Test edge cases + +### Test Types + +| Type | Location | Purpose | +|------|----------|---------| +| Unit | `tests/unit/` | Test individual functions | +| Integration | `tests/integration/` | Test component interactions | +| E2E | `tests/e2e/` | Test full user flows | +| Skills | `tests/skills/` | Test skill execution | + +## Code Style + +### JavaScript/TypeScript + +- Use ESLint configuration provided +- Prefer `const` over `let` +- Use meaningful variable names +- Add JSDoc comments for public APIs + +```javascript +/** + * Calculate agent health status + * @param {Object} agent - Agent instance + * @returns {Object} Health status + */ +function calculateHealth(agent) { + const metrics = collectMetrics(agent); + return { + status: metrics.status, + score: metrics.score + }; +} +``` + +### Formatting + +- Use Prettier for consistent formatting +- 2 spaces for indentation +- Single quotes for strings +- Semicolons required + +```bash +# Format code +npm run format + +# Check formatting +npm run format:check +``` + +## Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + +[optional body] + +[optional footer] +``` + +### Types + +- `feat:` New feature +- `fix:` Bug fix +- `docs:` Documentation changes +- `style:` Code style changes (formatting) +- `refactor:` Code refactoring +- `test:` Test additions/changes +- `chore:` Build/config changes + +### Examples + +``` +feat(agents): add historian agent for memory management + +Implements the historian agent responsible for long-term +memory consolidation and decision tracking. + +Closes #123 +``` + +``` +fix(gateway): resolve WebSocket connection timeout + +Increased timeout from 5s to 30s for slow connections. + +Fixes #456 +``` + +``` +docs(api): update A2A protocol documentation + +Added examples for new message types and clarified +error handling procedures. +``` + +## Documentation + +### Writing Documentation + +- Use clear, concise language +- Include examples where helpful +- Link to related documentation +- Keep headings hierarchical + +### Documentation Structure + +``` +docs/ +β”œβ”€β”€ getting-started/ +β”œβ”€β”€ architecture/ +β”œβ”€β”€ configuration/ +β”œβ”€β”€ operations/ +└── api/ +``` + +## Release Process + +### Version Numbering + +We use [Semantic Versioning](https://semver.org/): + +- `MAJOR.MINOR.PATCH` +- Breaking changes β†’ increment MAJOR +- New features β†’ increment MINOR +- Bug fixes β†’ increment PATCH + +### Release Checklist + +- [ ] Update version in package.json +- [ ] Update CHANGELOG.md +- [ ] Create git tag +- [ ] Publish to npm (if applicable) +- [ ] Create GitHub release + +## Questions? + +- **General questions:** GitHub Discussions +- **Bug reports:** GitHub Issues +- **Security issues:** Email security@heretek.ai + +--- + +Thank you for contributing to Heretek OpenClaw! 🦞 diff --git a/README.md b/README.md new file mode 100644 index 0000000..1292c78 --- /dev/null +++ b/README.md @@ -0,0 +1,252 @@ +# Heretek OpenClaw Core + +> Gateway, agents, A2A protocol, and core functionality for the Heretek OpenClaw autonomous agent collective. + +## Overview + +Heretek OpenClaw Core is the foundational repository containing: + +- **OpenClaw Gateway** - Central daemon managing agent workspaces and A2A communication +- **Agent Implementations** - 11+ specialized agents for various tasks +- **A2A Protocol** - Agent-to-Agent communication via WebSocket RPC +- **Skills Repository** - 48+ skills for agent operations +- **Plugin System** - Extensible plugin architecture + +## Installation + +### Prerequisites + +- Node.js 20+ +- PostgreSQL 15+ with pgvector extension +- Redis 7+ +- Ollama (optional, for local LLM) + +### Quick Start + +```bash +# Clone repository +git clone https://github.com/heretek/heretek-openclaw-core.git +cd heretek-openclaw-core + +# Install dependencies +npm install + +# Copy environment template +cp .env.example .env + +# Start services +docker compose up -d + +# Start Gateway +npm run gateway:start +``` + +## Usage + +### Starting the Gateway + +```bash +# Start Gateway daemon +npm run gateway:start + +# Check Gateway status +npm run gateway:status + +# Stop Gateway +npm run gateway:stop +``` + +### Agent Management + +```bash +# List available agents +npm run agents:list + +# Deploy an agent +npm run agents:deploy -- steward + +# View agent logs +npm run agents:logs -- steward +``` + +### Skills + +```bash +# List available skills +npm run skills:list + +# Execute a skill +npm run skills:run -- healthcheck +``` + +## Configuration + +### openclaw.json + +Main configuration file for the OpenClaw collective: + +```json +{ + "collective": { + "name": "heretek-openclaw", + "version": "2.0.0" + }, + "agents": { + "steward": { + "role": "orchestrator", + "model": "openai/gpt-4o" + } + }, + "a2a_protocol": { + "enabled": true, + "endpoint": "ws://localhost:18789" + } +} +``` + +### Environment Variables + +See `.env.example` for all available options: + +```bash +# LiteLLM Configuration +LITELLM_URL=http://localhost:4000 +LITELLM_MASTER_KEY=your-key-here + +# Database +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_USER=heretek +POSTGRES_PASSWORD=your-password + +# Redis +REDIS_HOST=localhost +REDIS_PORT=6379 +``` + +## Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Heretek OpenClaw Core β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ OpenClaw Gateway β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Steward β”‚ β”‚ Alpha β”‚ β”‚ Beta β”‚ β”‚ Charlie β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Orch) β”‚ β”‚ (Triad) β”‚ β”‚ (Triad) β”‚ β”‚ (Triad) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Sentinelβ”‚ β”‚ Explorerβ”‚ β”‚ Examinerβ”‚ β”‚ Coder β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Safety)β”‚ β”‚ (Research)β”‚(Advocate)β”‚(Developer)β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Dreamer β”‚ β”‚ Empath β”‚ β”‚ Historianβ”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Creative)β”‚(Support) β”‚ (Memory) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LiteLLM β”‚ β”‚ PostgreSQL β”‚ β”‚ Redis β”‚ β”‚ +β”‚ β”‚ :4000 β”‚ β”‚ :5432 β”‚ β”‚ :6379 β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## API Reference + +### Gateway WebSocket API + +Connect to the Gateway at `ws://localhost:18789`: + +```javascript +const WebSocket = require('ws'); +const ws = new WebSocket('ws://localhost:18789'); + +ws.on('open', () => { + ws.send(JSON.stringify({ + type: 'handshake', + agent: 'external-client' + })); +}); + +ws.on('message', (data) => { + const message = JSON.parse(data); + console.log('Received:', message); +}); +``` + +### Message Types + +| Type | Description | +|------|-------------| +| `message` | Standard agent message | +| `status` | Agent status update | +| `error` | Error notification | +| `event` | Gateway event | +| `handshake` | Connection handshake | +| `discovery` | Agent/service discovery | +| `proposal` | Triad proposal | +| `vote` | Triad vote | +| `decision` | Triad decision | + +## Testing + +```bash +# Run all tests +npm run test + +# Run unit tests +npm run test:unit + +# Run integration tests +npm run test:integration + +# Run with coverage +npm run test:coverage +``` + +## Development + +```bash +# Install dependencies +npm install + +# Run in development mode +npm run dev + +# Lint code +npm run lint + +# Format code +npm run format +``` + +## Documentation + +- [Architecture](docs/ARCHITECTURE.md) +- [A2A Protocol](docs/standards/A2A_PROTOCOL.md) +- [Skills](docs/SKILLS.md) +- [Plugins](docs/PLUGINS.md) +- [Operations](docs/OPERATIONS.md) + +## Related Repositories + +- [CLI](https://github.com/heretek/heretek-openclaw-cli) - Deployment CLI +- [Dashboard](https://github.com/heretek/heretek-openclaw-dashboard) - Health monitoring +- [Plugins](https://github.com/heretek/heretek-openclaw-plugins) - Plugin system +- [Deploy](https://github.com/heretek/heretek-openclaw-deploy) - Infrastructure as Code +- [Docs](https://github.com/heretek/heretek-openclaw-docs) - Documentation site + +## License + +MIT + +## Support + +- **Issues:** https://github.com/heretek/heretek-openclaw-core/issues +- **Discussions:** https://github.com/heretek/heretek-openclaw-core/discussions + +--- + +🦞 *The thought that never ends.*