@defai.digital/automatosx 8.5.4 → 9.0.1

package/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [9.0.1] - 2025-11-19
+
+### Fixed
+- **🐛 Critical Stability Fixes** - Multiple crash and hang prevention improvements
+  - **MCP Server Infinite Loop** - Added iteration limit (100/chunk), buffer size check (10MB), message size validation (5MB)
+  - **Memory Leaks** - Fixed AbortSignal listener cleanup in database connection pool
+  - **Stack Overflow** - Converted recursive `processWaitQueue()` to iterative (max 1000 iterations)
+  - **Resource Leaks** - Enhanced health check interval cleanup with multiple fallback handlers
+  - **Shutdown Hangs** - Added timeout protection (30s default) to all graceful shutdown handlers
+  - **Race Conditions** - Added mutex protection to MCP server initialization
+
+### Technical Details
+- **MCP Server (src/mcp/server.ts)** - Prevents infinite loops from malformed JSON-RPC messages
+- **Connection Pool (src/core/db-connection-pool.ts)** - Eliminates memory leaks in high-concurrency scenarios
+- **Graceful Shutdown (src/utils/graceful-shutdown.ts)** - Prevents process hanging on SIGTERM/SIGINT
+- **Performance** - All fixes have < 1ms overhead, zero performance impact
+
+### Testing
+- ✅ All 1000+ unit tests passing
+- ✅ TypeScript strict mode validation
+- ✅ Build verification successful
+- ✅ Zero breaking changes
+
+## [9.0.0] - 2025-11-18
+
+### Breaking Changes
+- **🚨 Cost-Based Budget Tracking Removed** - Token-based limits only
+  - Removed `--iterate-max-cost` CLI flag (use `--iterate-max-tokens`)
+  - Removed `maxEstimatedCostUsd` from configuration
+  - Removed `totalCost` from IterateStats (now optional/deprecated field)
+  - Removed `cost_limit_exceeded` pause reason (use `token_limit_exceeded`)
+  - Removed `enableCostTracking` from SafetyConfig
+  - Removed `warnAtCostPercent` from NotificationConfig
+  - Removed CostTracker class (~1,200 lines of code)
+
+### Removed
+- **CostTracker System** - Full removal of unreliable cost estimation
+  - Deleted `src/core/cost-tracker.ts` (597 lines)
+  - Deleted `src/core/cost-tracker-schemas.ts` (~100 lines)
+  - Deleted `src/types/cost.ts` (~150 lines)
+  - Deleted cost-related test files (~341 lines)
+  - Total reduction: ~1,200 lines of code
+
+### Changed
+- **Iterate Mode Budget System** - Token-only tracking
+  - Token limits are stable and accurate (never change)
+  - Budgets enforced via `maxTotalTokens` and `maxTokensPerIteration`
+  - Stats show token usage instead of cost estimates
+  - Status renderer displays tokens instead of dollars
+
+### Migration
+- See `docs/migration/v9-cost-to-tokens.md` for complete migration guide
+- Replace `--iterate-max-cost 5.0` with `--iterate-max-tokens 1000000`
+- Update config: `maxEstimatedCostUsd` → `maxTotalTokens`
+- Track costs manually if needed: `tokens * price_per_1M_tokens`
+
+### Why This Change
+- Provider pricing changes frequently without notice
+- Cost estimates were unreliable and caused user confusion
+- Token counts are stable and accurately tracked
+- Simpler codebase (~1,200 lines removed)
+- Zero maintenance burden for pricing updates
+
+## [8.6.0] - 2025-11-18
+
+### Added
+- **🎯 Token-Based Budget Limits for Iterate Mode** - More reliable than cost-based limits
+  - `--iterate-max-tokens` flag (default: 1,000,000 tokens)
+  - `--iterate-max-tokens-per-iteration` flag (default: 100,000 tokens)
+  - Progressive warnings at 75% and 90% of token budget
+  - Accurate tracking from provider API responses
+  - Token metrics in iterate stats (`totalTokens`, `avgTokensPerIteration`)
+
+- **📊 Token Budget Enforcement**
+  - Automatic pause when token limit exceeded
+  - Real-time token usage tracking
+  - Per-stage and total token counters
+  - New pause reason: `token_limit_exceeded`
+
+- **📖 Migration Guide** - Complete guide for migrating from cost to token limits
+  - `docs/migration/v9-cost-to-tokens.md`
+  - Conversion formulas and examples
+  - Timeline and breaking changes documented
+
+### Changed
+- **Better Budget Control** - Token limits more reliable than cost estimates
+  - Token counts never change (unlike provider pricing)
+  - Accurate usage from API responses (not estimates)
+  - No maintenance needed for pricing updates
+
+### Deprecated
+- **⚠️ Cost-Based Limits** - Will be removed in v9.0.0
+  - `--iterate-max-cost` flag (use `--iterate-max-tokens` instead)
+  - `maxEstimatedCostUsd` config field (use `maxTotalTokens` instead)
+  - Shows clear deprecation warnings with migration guidance
+  - Still functional in v8.6.0-v8.7.x for backward compatibility
+
+### Performance
+- Token tracking overhead: < 1ms per iteration
+- No performance regression
+- Build time: 650ms (unchanged)
+- Test suite: 25s (unchanged)
+
+### Testing
+- 34 new comprehensive token tracking tests
+- All 2,441 tests passing
+- Edge cases covered (zero limit, large limit, warnings)
+- Backward compatibility verified
+
+### Migration
+- Fully backward compatible (zero breaking changes)
+- Both cost and token flags work in v8.6.0-v8.7.x
+- Migration guide provides clear upgrade path
+- Breaking change deferred to v9.0.0
+
 ## [8.5.2] - 2025-11-18
 
 ### Added

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[support@defai.digital](mailto:support@defai.digital).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,427 @@
+# Contributing to AutomatosX
+
+Thank you for your interest in contributing to AutomatosX! This document provides guidelines for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Coding Standards](#coding-standards)
+
+## Code of Conduct
+
+This project follows a Code of Conduct (see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
+
+## Project Status & Contribution Policy
+
+AutomatosX is an **open source project** published for **transparency and community benefit**. While the entire codebase is public for review and learning:
+
+### What We Welcome ✅
+
+- **Bug Reports** - Please report issues via GitHub Issues
+- **Feature Suggestions** - Share your ideas for discussion
+- **Documentation Improvements** - Typos, clarifications, examples
+- **Security Reports** - See [SECURITY.md](SECURITY.md) for responsible disclosure
+- **Questions & Discussions** - Use GitHub Discussions
+- **Sharing & Using** - Use AutomatosX in your projects!
+
+### Current Development Model 🔧
+
+- This is **not actively seeking code contributions** at this time
+- The codebase is **fully transparent** for trust and verification
+- Development is primarily done by the core team
+- We may accept PRs on a case-by-case basis
+
+### Why This Approach?
+
+We believe in **radical transparency** - you should be able to:
+- ✅ Verify the code does what it claims
+- ✅ Audit security and privacy practices
+- ✅ Learn from the implementation
+- ✅ Trust that nothing harmful is hidden
+- ✅ Fork and modify for your own use (within license terms)
+
+This doesn't mean we don't value the community! Issues, discussions, and feedback are **highly appreciated** and help make AutomatosX better.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/yourusername/automatosx.git`
+3. Add upstream remote: `git remote add upstream https://github.com/automatosx/automatosx.git`
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 20.0.0 or later
+- npm, pnpm, or yarn
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev -- <command>
+```
+
+## Making Changes
+
+### Creating a Branch
+
+```bash
+# Update your main branch
+git checkout main
+git pull upstream main
+
+# Create a feature branch
+git checkout -b feature/your-feature-name
+```
+
+### Branch Naming Convention
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation changes
+- `test/` - Test improvements
+- `refactor/` - Code refactoring
+- `perf/` - Performance improvements
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Writing Tests
+
+- Write tests for all new features
+- Maintain or improve test coverage (current: ~85%)
+- Place unit tests in `tests/unit/`
+- Place integration tests in `tests/integration/`
+- Use descriptive test names
+- Follow existing test patterns
+
+### Test Requirements
+
+- All tests must pass before submitting PR
+- Coverage should not decrease
+- Add tests for bug fixes to prevent regression
+
+## Submitting Changes
+
+### Before Submitting
+
+1. **Run tests**: `npm test`
+2. **Type check**: `npm run typecheck`
+3. **Build**: `npm run build`
+4. **Update documentation** if needed
+5. **Update CHANGELOG.md** with your changes
+
+### Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/) specification. This enables automated changelog generation and semantic versioning.
+
+#### Quick Start
+
+Use the interactive commit tool:
+
+```bash
+npm run commit
+```
+
+Or write manually:
+
+```bash
+git commit -m "feat(agents): add delegation depth validation"
+```
+
+#### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Required**:
+- `type`: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert
+- `subject`: Short description (max 100 chars, lowercase, no period)
+
+**Optional**:
+- `scope`: Module affected (agents, cli, memory, router, providers, etc.)
+- `body`: Detailed explanation
+- `footer`: Issue references, breaking changes
+
+#### Examples
+
+```bash
+# Feature
+feat(agents): add delegation depth validation
+
+# Bug fix
+fix(cli): resolve path resolution bug in Windows
+
+# Documentation
+docs: update release process guide
+
+# Breaking change
+feat(router)!: remove deprecated fallback option
+
+BREAKING CHANGE: The `enableFallback` option has been removed.
+Use `fallbackChain` instead.
+```
+
+#### Commit Hooks
+
+Git hooks will validate your commit messages:
+- Invalid commits will be rejected
+- Use `npm run commit` for guided input
+- See [docs/conventional-commits.md](./docs/conventional-commits.md) for full guide
+
+#### Benefits
+
+- 📝 Automated CHANGELOG generation
+- 🏷️ Semantic version automation
+- 📊 Clear commit history
+- 🤝 Better collaboration
+
+### Pull Request Process
+
+1. **Update your branch**:
+
+   ```bash
+   git checkout main
+   git pull upstream main
+   git checkout your-branch
+   git rebase main
+   ```
+
+2. **Push to your fork**:
+
+   ```bash
+   git push origin your-branch
+   ```
+
+3. **Create Pull Request**:
+   - Use a clear, descriptive title
+   - Reference related issues
+   - Describe what changed and why
+   - Include screenshots for UI changes
+   - List breaking changes if any
+
+4. **PR Template**:
+
+   ```markdown
+   ## Description
+   Brief description of changes
+
+   ## Type of Change
+   - [ ] Bug fix
+   - [ ] New feature
+   - [ ] Breaking change
+   - [ ] Documentation update
+
+   ## Testing
+   - [ ] Tests pass locally
+   - [ ] Added/updated tests
+   - [ ] Manual testing completed
+
+   ## Checklist
+   - [ ] Code follows project style
+   - [ ] Documentation updated
+   - [ ] CHANGELOG.md updated
+   - [ ] No breaking changes (or documented)
+   ```
+
+5. **Review Process**:
+   - Address reviewer feedback
+   - Make requested changes
+   - Push updates to your branch
+   - Re-request review when ready
+
+## Coding Standards
+
+### TypeScript
+
+- Use TypeScript strict mode
+- Provide type annotations for all public APIs
+- Avoid `any` type unless absolutely necessary
+- Use meaningful variable and function names
+- Keep functions small and focused
+
+### Code Style
+
+```typescript
+// Good
+export async function loadProfile(
+  profilePath: string,
+  options: LoadOptions = {}
+): Promise<AgentProfile> {
+  // Implementation
+}
+
+// Bad
+export async function load(p: string, o: any) {
+  // Implementation
+}
+```
+
+### Documentation
+
+- Add JSDoc comments for all public APIs
+- Include parameter descriptions
+- Document return types
+- Provide usage examples
+
+```typescript
+/**
+ * Load an agent profile from a YAML file.
+ *
+ * @param profilePath - Absolute path to the profile file
+ * @param options - Optional loading configuration
+ * @returns Parsed agent profile
+ * @throws {PathTraversalError} If path is outside allowed directory
+ *
+ * @example
+ * ```typescript
+ * const profile = await loadProfile('/path/to/agent.yaml');
+ * console.log(profile.name); // 'my-agent'
+ * ```
+ */
+export async function loadProfile(
+  profilePath: string,
+  options: LoadOptions = {}
+): Promise<AgentProfile> {
+  // Implementation
+}
+```
+
+### File Organization
+
+```
+src/
+├── core/           # Core modules
+├── agents/         # Agent system
+├── providers/      # AI provider integrations
+├── cli/            # CLI commands
+├── types/          # TypeScript types
+└── utils/          # Utility functions
+```
+
+### Error Handling
+
+- Use custom error classes
+- Provide meaningful error messages
+- Include error context
+- Handle errors gracefully
+
+```typescript
+// Good
+if (!isValidPath(path)) {
+  throw new PathTraversalError(
+    `Invalid path: ${path}`,
+    { path, allowedDir }
+  );
+}
+
+// Bad
+if (!isValidPath(path)) {
+  throw new Error('bad path');
+}
+```
+
+### Performance
+
+- Avoid unnecessary computations
+- Use caching where appropriate
+- Lazy load when possible
+- Profile performance-critical code
+
+## Project Structure
+
+### Important Files
+
+- `src/` - Source code
+- `tests/` - Test suites
+- `docs/` - Documentation
+- `PRD/` - Product requirements
+- `examples/` - Example configurations
+
+### Key Modules
+
+1. **Core** (`src/core/`)
+   - `config.ts` - Configuration management
+   - `logger.ts` - Logging system
+   - `path-resolver.ts` - Path resolution
+   - `memory-manager.ts` - Memory persistence
+   - `router.ts` - Provider routing
+
+2. **Agents** (`src/agents/`)
+   - `profile-loader.ts` - Profile loading
+   - `abilities-manager.ts` - Abilities management
+   - `context-manager.ts` - Execution context
+
+3. **CLI** (`src/cli/`)
+   - Command implementations
+   - User interface
+
+## Release Process
+
+See [docs/release-process.md](./docs/release-process.md) for detailed release instructions.
+
+Quick summary:
+1. Update version: `npm run version:patch`
+2. Push: `git push && git push --tags`
+3. GitHub Actions handles the rest automatically
+
+## Getting Help
+
+- Check existing [documentation](docs/)
+- Search [existing issues](https://github.com/defai-digital/automatosx/issues)
+- Open a new issue for questions, bugs, or feature requests
+  - Use "bug" label for bugs
+  - Use "enhancement" label for feature requests/wishlist
+  - Use "question" label for questions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Elastic License 2.0.
+
+## Recognition
+
+Contributors will be recognized in:
+
+- CHANGELOG.md
+- GitHub contributors page
+- Release notes (for significant contributions)
+
+Thank you for contributing to AutomatosX! 🚀