axiom-unified 0.1.0

package/.prettierignore

@@ -0,0 +1,4 @@
+dist/
+node_modules/
+scratch/
+*.md

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to Axiom Unified will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] — v0.1.0 (planned)
+
+### Added
+- AXIOM_HOME centralization for full test isolation
+- Live provider gauntlet passed (Groq, Cerebras, NVIDIA, Mistral)
+
+### Fixed
+- Telemetry receipts directory creation in fresh AXIOM_HOME
+- Shell classification for simple del/rm commands without flags
+
+### Planned
+- Dead code removal (unreachable isDangerousCommand fallback)
+- npm publication decision and preparation
+
+## [0.1.0-pre] — 2026-05-10
+
+### Added
+- Daemon mode with token-based authentication and request serialization
+- Daemon retry safety: no duplicate execution for done-with-no-output responses
+- Request-scoped terminal output capture via `terminal.setOutputStream()`
+- Shell command classification: read_only, modify, destructive, publish, service
+- Expanded dangerous pattern detection: Windows destructive commands, package managers, service ops, system file redirections
+- `AXIOM_HOME` environment variable for daemon protocol test isolation
+- CI workflow: check, lint, format:check, test, build on push/PR
+- 16 test suites (0 failures) with test runner isolation
+
+### Changed
+- Package version: `1.0.0` → `0.1.0` (truthful pre-release)
+- `engines.node`: `>=18.0.0` (aligned with CI Node 22)
+- README: clarified "local runtime, external-provider powered"
+- Daemon stdout: replaced global `process.stdout.write` hijacking with request-scoped `Writable` stream
+- `docs/CURRENT_STATUS.md`: updated test suite count and current readiness
+
+### Fixed
+- Daemon client: no longer retries after receiving a `done` response
+- Daemon protocol tests: isolated from real `~/.axiom` via `AXIOM_HOME`
+- Shell classification: dangerous patterns checked before read-only patterns
+- Shell classification: `mv` and `cp` correctly classified as modify, not destructive
+- Unused `path` import removed from `src/daemon/server.ts`
+
+### Known Limitations
+- `AXIOM_HOME` only isolates daemon protocol paths; runtime paths still hardcode `~/.axiom`
+- No live provider gauntlet has been run
+- Not published to npm
+- `isDangerousCommand` fallback in `tools-core.ts` is unreachable (documented, kept as defensive code)
+
+## [0.1.0-dev] — 2026-05-07/08
+
+### Added
+- Initial standalone repo setup (EchoEe247/axiom-unified)
+- CLI daemon/client mode with `axiom`, `axiom serve`, `axiom stop`, `axiom status`
+- Multi-provider fallback with Groq, Cerebras, NVIDIA, and Mistral
+- Tool registry with JSON schemas and confirmation gates
+- Session persistence and memory recall
+- Knowledge graph for structured context
+- Safety gates for destructive operations
+- Provider catalog tests and benchmark dry-runs
+- 30+ tools for coding and project work
+- Autonomous agency components (planner, executor, learner)
+- Telegram bot mode (optional)
+- Social and video tools (optional, require external credentials)
+- 6-phase remediation: security fixes, code hygiene, mega-file decomposition, test hardening, autonomous agency, documentation
+- ESLint + Prettier configuration
+- Test runner with try/catch isolation for all suites
+- Runnable examples in `examples/`
+- Architecture docs with Mermaid diagrams
+- TypeDoc configuration
+- Open source documentation (CONTRIBUTING.md, CODE_OF_CONDUCT.md)
+
+### Technical Details
+- Built with TypeScript 5.7
+- Uses OpenAI-compatible API endpoints
+- Modular tool system with safety gates
+- Persistent session storage
+- Vector-based memory recall
+- Entity-relationship knowledge graph
+- Terminal-first local agent runtime
+- Free tier focused (all providers use free tiers)

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,118 @@
+# 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, 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 e-mail 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
+[INSERT CONTACT METHOD].
+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].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,163 @@
+# Contributing to Axiom Unified
+
+Thank you for your interest in contributing to Axiom Unified! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+- Check if the bug has already been reported in [Issues](../../issues)
+- Use the bug report template
+- Include steps to reproduce, expected behavior, and actual behavior
+- Include relevant logs, screenshots, or error messages
+
+### Suggesting Enhancements
+- Check if the enhancement has already been suggested
+- Use the feature request template
+- Clearly describe the enhancement and its benefits
+- Consider if it aligns with Axiom's focus as a free daily coding agent
+
+### Pull Requests
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`npm test`)
+5. Ensure code passes TypeScript check (`npm run check`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to your branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## Development Setup
+
+### Prerequisites
+- Node.js 18 or higher
+- npm 8 or higher
+
+### Installation
+```bash
+git clone https://github.com/your-username/axiom-unified.git
+cd axiom-unified
+npm install
+npm run build
+```
+
+### Running Tests
+```bash
+npm test            # Run all 13 test suites via test runner
+npm run check       # TypeScript type checking
+npm run build       # Build the project
+npm run lint        # ESLint check
+npm run format      # Prettier auto-format
+```
+
+Individual test suites:
+```bash
+npm run test:autonomous-agency
+npm run test:knowledge-graph
+npm run test:fallback-simulation
+npm run test:consensus-routing
+npm run test:provider-catalog
+npm run test:engine-benchmark
+npm run test:examples
+npm run test:reflection-injection
+```
+
+### Running Examples
+```bash
+npm run example:hello
+npm run example:file-ops
+npm run example:code-review
+npm run example:multi-step
+npm run example:autonomous
+```
+
+### Generating Docs
+```bash
+npm run docs         # Generate TypeDoc API docs to docs/api/
+```
+
+### Development Workflow
+1. Make changes in the `src/` directory
+2. Run `npm run check` to verify TypeScript compilation
+3. Run `npm run lint` to check code style
+4. Run `npm test` to ensure nothing is broken
+5. Build to verify compilation (`npm run build`)
+6. Test your changes manually if needed
+
+## Coding Standards
+
+### TypeScript
+- Use strict TypeScript configuration
+- Add type annotations for function parameters and return types
+- Use interfaces for complex data structures
+- Avoid `any` type when possible
+
+### Code Style
+- Use 2-space indentation
+- Use meaningful variable and function names
+- Add JSDoc comments for public APIs
+- Keep functions focused and single-purpose
+
+### Tool Development
+When adding new tools:
+1. Add tool implementation in `src/tools/`
+2. Register tool in `src/tools/registry.ts`
+3. Add appropriate safety gates if needed
+4. Add tests for the new tool
+5. Update documentation
+
+## Project Structure
+
+```
+src/
+├── core/           # Core systems (memory, knowledge graph, context)
+├── runtime/        # Runtime systems (loop, dispatcher, planner)
+│   ├── loop/       # Loop sub-modules (tool extraction, execution, synthesis)
+│   ├── commands/   # Command registry sub-modules
+│   └── autonomous/ # Autonomous agency (orchestrator, planner, learner)
+├── tools/          # Tool implementations
+│   └── registry/   # Registry sub-modules (core, safety, tool categories)
+├── daemon/         # Daemon/client architecture
+├── persistence/    # Session storage
+└── providers.ts    # Multi-provider client
+
+examples/           # Runnable example files
+docs/               # Documentation
+  ├── ARCHITECTURE.md  # System architecture with diagrams
+  ├── API.md           # API reference
+  └── CURRENT_STATUS.md # Current project status
+```
+
+## Safety Guidelines
+
+Axiom has a safety-first approach:
+
+### Tool Safety Gates
+- Destructive operations require confirmation
+- File writes require confirmation
+- External side effects (publishing, social) are gated
+- Provider usage respects free tier limits
+
+### Adding New Tools
+- Consider safety implications
+- Add appropriate confirmation gates
+- Respect user privacy and data
+- Follow the principle of least privilege
+
+## Documentation
+
+- Update README.md if adding significant features
+- Add JSDoc comments for new APIs
+- Update relevant documentation in `docs/`
+- Add examples if introducing new functionality
+
+## Questions?
+
+- Check existing documentation in `docs/`
+- Search existing issues and discussions
+- Ask in GitHub Discussions (if enabled)
+
+Thank you for contributing to Axiom Unified!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axiom Unified contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# Axiom Unified
+
+<p align="center">
+  <strong>Free Daily Local Agent Specialized in Coding & Project Work</strong>
+</p>
+
+<p align="center">
+  <!-- Badges will be added when CI is set up -->
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7-blue" alt="TypeScript"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18+-green" alt="Node.js"></a>
+</p>
+
+Axiom Unified is a **free daily local agent** specialized in coding and project work. It runs locally on your machine and connects to external AI providers for inference. Designed to be your terminal-first coding companion with safety gates, provider fallback, and 30+ coding-specific tools.
+
+**Why Axiom?**
+- 🆓 **Free tier focused** - All providers use free tiers
+- 🔒 **Safety first** - Confirmation gates for destructive operations  
+- 🛠️ **Coding specialized** - 30+ tools for project work
+- 🧠 **Memory aware** - Remembers context across sessions
+- ⚡ **Local runtime** - Terminal-first, external-provider powered
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone and install
+git clone https://github.com/EchoEe247/axiom-unified.git
+cd axiom-unified
+npm install
+npm run build
+
+# Verify installation
+node dist/index.js "what can you do?"
+```
+
+### Your First Command
+
+```bash
+# Analyze your current project
+node dist/index.js analyze-project
+
+# Run autonomous agent with a complex goal
+node dist/index.js "optimize build process" --auto
+
+# Visualize the Project Knowledge Graph
+node dist/index.js map
+```
+
+## ✨ Features
+
+### 🛠️ Coding Specialization
+- **Autonomous Agency**: Run complex, multi-step goals with `--auto`
+- **Project Analysis**: `analyze-project`, `detect-tech-stack`
+- **Project Mapping**: `/map` to visualize Knowledge Graph
+- **Code Quality**: `security-scan`, `complexity`, `test-coverage`
+- **Refactoring**: `refactor-suggest`, `bug-predict`
+- **Integration**: `ide-integration`, `ci-cd`, `cloud-integration`
+
+### 🔒 Safety First
+- **Confirmation Gates**: File writes, shell commands, git operations
+- **Provider Limits**: Free tier monitoring and fallback
+- **Memory Controls**: Context-aware with privacy safeguards
+- **Tool Permissions**: Granular control over tool access
+
+### 🧠 Intelligent Systems
+- **Persistent Memory**: Remembers context across sessions
+- **Knowledge Graph**: Entity-relationship understanding
+- **Provider Fallback**: Groq → Cerebras → NVIDIA → Mistral
+- **Autonomous Components**: Planner, executor, experience learner
+
+### ⚡ Performance
+- **Terminal-First**: No GUI required, works in any terminal
+- **Daemon Mode**: Persistent sessions with `axiom serve`
+- **Fast Startup**: Quick response times
+- **Minimal Dependencies**: Clean TypeScript codebase
+
+## 📖 Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md) - Quick start guide
+- [Operating Guide](docs/OPERATING_GUIDE.md) - Comprehensive feature guide
+- [Provider Setup](docs/PROVIDERS.md) - Free tier configuration
+- [Safety Model](docs/SAFE_CAPABILITIES.md) - Safety features and gates
+- [Examples](examples/) - Practical usage examples
+
+## 🏗️ Architecture
+
+```
+src/
+├── core/           # Core systems (memory, knowledge graph, context)
+├── runtime/        # Runtime systems (loop, dispatcher, planner)
+├── tools/          # 30+ tool implementations
+├── daemon/         # Daemon/client architecture
+├── persistence/    # Session storage
+└── providers.ts    # Multi-provider client
+```
+
+## 🔧 Development
+
+### Prerequisites
+- Node.js 18+
+- npm 8+
+
+### Development Commands
+```bash
+npm install          # Install dependencies
+npm run check        # TypeScript compilation check
+npm test             # Run test suite
+npm run build        # Build project
+npm run serve        # Start daemon mode
+```
+
+### Adding New Tools
+1. Add tool implementation in `src/tools/`
+2. Register tool in `src/tools/registry.ts`
+3. Add appropriate safety gates
+4. Add tests
+5. Update documentation
+
+## 🤝 Contributing
+
+We welcome contributions! Please see:
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community standards
+- [CHANGELOG.md](CHANGELOG.md) - Release history
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🔗 Links
+
+- **Examples**: [examples/](examples/) - Practical usage examples
+- **Issues**: [GitHub Issues](../../issues) - Bug reports and feature requests
+- **Discussions**: [GitHub Discussions](../../discussions) - Community discussions
+
+---
+
+<p align="center">
+  <em>Built with ❤️ for developers who want a free, safe, and capable coding companion.</em>
+</p>