Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (120 loc) · 3.92 KB

CONTRIBUTING.md

File metadata and controls

159 lines (120 loc) · 3.92 KB

Contributing to AgentOS Extensions

Thank you for your interest in contributing to the AgentOS Extensions ecosystem!

Getting Started

  1. Fork the repository: https://github.com/framerslab/agentos-extensions
  2. Clone your fork: 
    git clone https://github.com/yourusername/agentos-extensions
cd agentos-extensions
pnpm install
  3. Create a feature branch: 
    git checkout -b feat/my-extension

Creating a New Extension

  1. Use the scaffolding script or copy a template:

    pnpm run create-extension
# or
cp -r templates/basic-tool registry/curated/category/my-extension

  2. Configure your extension:

    • Update package.json:
      • Set "name" to @framers/agentos-ext-{name}
      • Set "private": false
      • Add "publishConfig": { "access": "public" }
    • Update manifest.json with proper metadata
    • Implement tools in src/tools/

  3. Add to the workspace:

    • Add your package path to pnpm-workspace.yaml

  4. Follow the standards:

    • Use TypeScript with strict mode
    • Implement the ITool interface correctly
    • Include comprehensive tests (>80% coverage)
    • MIT license

Package Naming

All extensions use the @framers/agentos-ext-{name} pattern:

Package Name
Auth @framers/agentos-ext-auth
Web Search @framers/agentos-ext-web-search
Web Browser @framers/agentos-ext-web-browser
Telegram @framers/agentos-ext-telegram
CLI Executor @framers/agentos-ext-cli-executor

Development

Code Quality

  • Linting: pnpm run lint
  • Type checking: pnpm run build
  • Testing: pnpm run test (maintain >80% coverage)
  • Documentation: Update README with examples

Testing Locally

cd registry/curated/category/my-extension
pnpm test

Integration with AgentOS

import { AgentOS } from '@framers/agentos';
import myExtension from '@framers/agentos-ext-my-extension';

const agentos = new AgentOS();
await agentos.initialize({
  extensionManifest: {
    packs: [{
      factory: () => myExtension({ /* options */ })
    }]
  }
});

Pull Request Process

  1. Ensure all checks pass:

    pnpm test
pnpm run lint
pnpm run build

  2. Add a changeset describing your changes:

    pnpm changeset

    Select your package, choose the bump type (patch/minor/major), and describe the change.

  3. Create pull request with:

    • Title: feat: add [extension-name] extension
    • What the extension does
    • Configuration required
    • Example usage

  4. Automated CI checks will:

    • Validate extension structure
    • Run linting and tests on Node 18 & 20
    • Check test coverage
    • Build the extension
    • Security scanning

After Your PR is Merged

Once merged to master:

  1. The Release workflow detects pending changesets
  2. A "chore: version packages" PR is auto-created with version bumps
  3. When that PR is merged, packages are published to npm
  4. GitHub releases are created with changelogs
  5. registry.json is updated

See RELEASING.md for the full publishing workflow.

Extension Guidelines

Security

  • Never hardcode API keys or secrets
  • Use environment variables for sensitive data
  • Validate all inputs
  • Handle errors gracefully

Performance

  • Keep bundle size minimal
  • Use async/await properly
  • Implement timeouts for external calls
  • Cache results when appropriate

Compatibility

  • Specify minimum AgentOS version in peerDependencies
  • Handle missing configuration gracefully
  • Provide sensible defaults

Getting Help

License

By contributing, you agree that your contributions will be licensed under the MIT License.