aios-core 2.1.0

package/.aios-core/infrastructure/tools/README.md

@@ -0,0 +1,222 @@
+# AIOS Tools - Integrations Directory
+
+This directory contains tool integration definitions for AIOS-FULLSTACK agents. Tools are external capabilities that agents can discover and use to accomplish tasks.
+
+## Directory Structure
+
+```
+tools/
+├── cli/            # Command-line tool integrations
+├── local/          # Local system tools
+└── mcp/            # Model Context Protocol (MCP) server definitions
+```
+
+## CLI Tools
+
+Command-line tools that agents can invoke for specific operations.
+
+### Available CLI Tools
+
+- **github-cli.yaml** - GitHub CLI (`gh`) integration
+  - Repository management
+  - Pull request operations
+  - Issue tracking
+  - Branch protection
+  - Release management
+
+- **railway-cli.yaml** - Railway CLI integration
+  - Deployment management
+  - Service configuration
+  - Environment variables
+  - Logs and monitoring
+
+- **supabase-cli.yaml** - Supabase CLI integration
+  - Database migrations
+  - Function deployment
+  - Project management
+  - Local development
+
+## Local Tools
+
+System tools available on the local machine.
+
+### Available Local Tools
+
+- **ffmpeg.yaml** - FFmpeg multimedia framework
+  - Video/audio conversion
+  - Media processing
+  - Codec operations
+  - Streaming preparation
+
+## MCP Integrations
+
+Model Context Protocol servers that provide specialized AI capabilities.
+
+### Available MCP Servers
+
+#### UI & Development
+- **21st-dev-magic.yaml** - UI component generation
+  - React component creation
+  - Design pattern implementation
+  - Component libraries integration
+
+#### Web & Research
+- **browser.yaml** - Browser automation
+  - Web scraping
+  - UI testing
+  - Screenshot capture
+  - Navigation automation
+
+- **exa.yaml** - Advanced web research
+  - Semantic search
+  - Academic paper search
+  - Competitor analysis
+  - Web crawling
+
+- **context7.yaml** - Documentation search
+  - Real-time library documentation
+  - Code examples
+  - API reference
+  - Version-specific docs
+
+#### Project Management
+- **clickup.yaml** - ClickUp integration
+  - Task management
+  - Sprint planning
+  - Story tracking
+  - Team collaboration
+
+#### Backend Services
+- **google-workspace.yaml** - Google Workspace APIs
+  - Drive file operations
+  - Docs editing
+  - Sheets manipulation
+  - Calendar management
+
+- **supabase.yaml** - Supabase backend
+  - Database operations
+  - Authentication
+  - Storage management
+  - Edge functions
+
+#### Automation
+- **n8n.yaml** - Workflow automation
+  - Integration workflows
+  - Data transformation
+  - API orchestration
+  - Event-driven automation
+
+## Using Tools in Agents
+
+### Discovery
+
+Agents can discover available tools using the tool resolver:
+
+```javascript
+const { resolveTools } = require('../utils/tool-resolver');
+
+// Get all available tools
+const tools = await resolveTools();
+
+// Get tools by category
+const mcpServers = await resolveTools({ category: 'mcp' });
+const cliTools = await resolveTools({ category: 'cli' });
+```
+
+### Configuration
+
+Each tool YAML file contains:
+
+```yaml
+name: tool-name
+category: cli|local|mcp
+description: "What this tool does"
+capabilities:
+  - capability-1
+  - capability-2
+installation:
+  method: npm|binary|built-in
+  command: "installation command"
+usage:
+  examples:
+    - description: "Example use case"
+      command: "command to execute"
+authentication:
+  required: true|false
+  method: "auth method"
+  envVars:
+    - ENV_VAR_NAME
+```
+
+### Best Practices
+
+1. **Check Tool Availability**: Always verify tool is installed before using
+2. **Handle Errors**: Tools may fail - implement graceful error handling
+3. **Respect Rate Limits**: Many tools have API rate limits
+4. **Secure Credentials**: Never hardcode credentials - use environment variables
+5. **Use tool-resolver**: Let the resolver handle tool discovery and validation
+
+## Adding New Tools
+
+### CLI Tool
+
+1. Create YAML file in `cli/`
+2. Define tool metadata and capabilities
+3. Specify installation method
+4. Provide usage examples
+5. Update this README
+
+### MCP Server
+
+1. Create YAML file in `mcp/`
+2. Define server connection details
+3. Document available capabilities
+4. Specify authentication requirements
+5. Test with `tool-resolver.js`
+
+### Local Tool
+
+1. Create YAML file in `local/`
+2. Verify tool is commonly available
+3. Document system requirements
+4. Provide installation instructions
+5. Test on target platforms
+
+## Troubleshooting
+
+### Tool Not Found
+
+```bash
+# Verify tool is in tools/ directory
+ls -la .aios-core/tools/cli/
+ls -la .aios-core/tools/local/
+ls -la .aios-core/tools/mcp/
+
+# Test tool resolver
+node .aios-core/scripts/tool-resolver.js
+```
+
+### Authentication Issues
+
+- Check environment variables are set
+- Verify API keys are valid
+- Check token expiration
+- Review tool-specific auth docs
+
+### MCP Connection Failures
+
+- Verify MCP server is running
+- Check network connectivity
+- Review server logs
+- Validate configuration YAML
+
+## Related Documentation
+
+- [Tool Resolver Utility](../utils/README.md#tool-resolver)
+- [Agent Guide](../../docs/agent-guide.md)
+- [MCP Specification](https://modelcontextprotocol.io)
+- [Core Configuration](../core-config.yaml)
+
+---
+
+*Last updated: 2025-10-22 - Documentation Sync Initiative*

package/.aios-core/infrastructure/tools/cli/github-cli.yaml

@@ -0,0 +1,200 @@
+tool:
+  schema_version: 1.0
+  id: github-cli
+  type: cli
+  name: GitHub CLI
+  version: 1.0.0
+  description: Official GitHub command-line interface for repository management, PR operations, issue tracking, and GitHub Actions
+  knowledge_strategy: declarative
+
+  capabilities:
+    - Repository management (create, clone, view)
+    - Pull request operations (create, review, merge, list)
+    - Issue management (create, list, view, comment)
+    - GitHub Actions workflow management
+    - Release management
+    - Gist operations
+    - Organization and team management
+    - Authentication and configuration
+
+  use_cases:
+    - pr_workflow: "Create and manage pull requests from CLI"
+    - issue_tracking: "Track and update issues without leaving terminal"
+    - ci_monitoring: "View and manage GitHub Actions workflow runs"
+    - repo_operations: "Clone, create, and manage repositories"
+    - code_review: "Review and approve pull requests"
+    - release_management: "Create and manage GitHub releases"
+
+  installation:
+    windows: "winget install --id GitHub.cli"
+    macos: "brew install gh"
+    linux: "See https://github.com/cli/cli/blob/trunk/docs/install_linux.md"
+
+  cli_specific:
+    executable: "gh"
+    configuration:
+      auth_check: "gh auth status"
+      login: "gh auth login"
+      config_file: "~/.config/gh/config.yml"
+      hosts_file: "~/.config/gh/hosts.yml"
+
+  command_groups:
+    repository:
+      - command: "gh repo create"
+        description: "Create a new repository"
+        common_flags:
+          - "--public / --private"
+          - "--clone"
+          - "--description"
+
+      - command: "gh repo clone"
+        description: "Clone a repository"
+        usage: "gh repo clone OWNER/REPO [DIRECTORY]"
+
+      - command: "gh repo view"
+        description: "View repository details"
+        common_flags:
+          - "--web (open in browser)"
+          - "--json (output as JSON)"
+
+    pull_request:
+      - command: "gh pr create"
+        description: "Create a pull request"
+        common_flags:
+          - "--title / -t"
+          - "--body / -b"
+          - "--base / -B"
+          - "--draft"
+          - "--web"
+
+      - command: "gh pr list"
+        description: "List pull requests"
+        common_flags:
+          - "--state (open, closed, merged, all)"
+          - "--author"
+          - "--assignee"
+
+      - command: "gh pr view"
+        description: "View a pull request"
+        usage: "gh pr view [NUMBER]"
+        common_flags:
+          - "--web"
+          - "--comments"
+
+      - command: "gh pr merge"
+        description: "Merge a pull request"
+        common_flags:
+          - "--merge / --squash / --rebase"
+          - "--delete-branch"
+          - "--auto"
+
+    issue:
+      - command: "gh issue create"
+        description: "Create an issue"
+        common_flags:
+          - "--title / -t"
+          - "--body / -b"
+          - "--assignee / -a"
+          - "--label / -l"
+
+      - command: "gh issue list"
+        description: "List issues"
+        common_flags:
+          - "--state (open, closed, all)"
+          - "--author"
+          - "--assignee"
+
+      - command: "gh issue view"
+        description: "View an issue"
+        usage: "gh issue view [NUMBER]"
+
+      - command: "gh issue comment"
+        description: "Add a comment to an issue"
+        usage: "gh issue comment NUMBER --body TEXT"
+
+    workflow:
+      - command: "gh run list"
+        description: "List workflow runs"
+        common_flags:
+          - "--workflow"
+          - "--branch"
+          - "--status"
+
+      - command: "gh run view"
+        description: "View a workflow run"
+        usage: "gh run view [RUN_ID]"
+        common_flags:
+          - "--log"
+          - "--log-failed"
+
+      - command: "gh run watch"
+        description: "Watch a workflow run"
+        usage: "gh run watch [RUN_ID]"
+
+      - command: "gh workflow run"
+        description: "Trigger a workflow"
+        usage: "gh workflow run WORKFLOW_NAME"
+
+    api:
+      - command: "gh api"
+        description: "Make authenticated GitHub API requests"
+        usage: "gh api ENDPOINT [flags]"
+        common_flags:
+          - "--method / -X"
+          - "--field / -f"
+          - "--raw-field / -F"
+          - "--header / -H"
+        examples:
+          - "gh api repos/:owner/:repo"
+          - "gh api user/memberships"
+          - "gh api repos/:owner/:repo/pulls/NUMBER/comments"
+
+  best_practices:
+    - "Always authenticate before using: gh auth status"
+    - "Use --json flag for programmatic output"
+    - "Set default repository context: gh repo set-default"
+    - "Use aliases for common commands: gh alias set"
+    - "Combine with jq for JSON processing: gh api | jq"
+    - "Use --web flag to open things in browser"
+
+  authentication:
+    - method: "OAuth token"
+      setup: "gh auth login"
+      scopes: "repo, workflow, admin:org, gist"
+    - method: "Personal Access Token"
+      setup: "gh auth login --with-token"
+      env_var: "GITHUB_TOKEN"
+
+  integration_patterns:
+    with_git:
+      - "gh repo clone → git operations → gh pr create"
+      - "git commit → git push → gh pr create"
+
+    with_ci:
+      - "gh run list to check status"
+      - "gh run view --log-failed for debugging"
+      - "gh workflow run to trigger builds"
+
+    with_scripts:
+      - "Use --json output for parsing"
+      - "Check exit codes for automation"
+      - "Use GITHUB_TOKEN for CI environments"
+
+  error_handling:
+    not_authenticated:
+      error: "You are not logged into any GitHub hosts"
+      solution: "Run 'gh auth login' to authenticate"
+
+    insufficient_permissions:
+      error: "Resource not accessible by integration"
+      solution: "Check authentication scopes and repository access"
+
+    rate_limit:
+      error: "API rate limit exceeded"
+      solution: "Wait for rate limit reset or use authenticated requests"
+
+  limitations:
+    - "Requires GitHub account"
+    - "Rate limits apply (higher for authenticated requests)"
+    - "Some operations require repository write access"
+    - "Not all GitHub API features exposed via CLI"

package/.aios-core/infrastructure/tools/cli/llm-routing.yaml

@@ -0,0 +1,126 @@
+# LLM Routing Tool Definition
+# Location: .aios-core/infrastructure/tools/cli/llm-routing.yaml
+# Version: 1.0.0
+
+tool:
+  id: llm-routing
+  name: LLM Routing
+  version: 1.0.0
+  category: cli
+  description: |
+    Cost-effective LLM routing for Claude Code.
+    Provides two commands for different use cases:
+    - claude-max: Uses Claude Max subscription via OAuth (~$15/M tokens)
+    - claude-free: Uses DeepSeek API (~$0.14/M tokens)
+
+capabilities:
+  - Install claude-max and claude-free commands
+  - Cross-platform support (Windows CMD, Unix bash)
+  - Automatic .env file detection for API keys
+  - Cost optimization for development workflows
+
+installation:
+  method: script
+  script: .aios-core/infrastructure/scripts/llm-routing/install-llm-routing.js
+  templates_dir: .aios-core/infrastructure/scripts/llm-routing/templates/
+
+  # Files installed
+  windows:
+    - name: claude-free.cmd
+      target: "%APPDATA%/npm/claude-free.cmd"
+    - name: claude-max.cmd
+      target: "%APPDATA%/npm/claude-max.cmd"
+
+  unix:
+    - name: claude-free.sh
+      target: "/usr/local/bin/claude-free"
+      permissions: "755"
+    - name: claude-max.sh
+      target: "/usr/local/bin/claude-max"
+      permissions: "755"
+
+usage:
+  claude-max:
+    description: "Premium Claude experience using Max subscription"
+    command: "claude-max"
+    authentication: OAuth (claude.ai login)
+    cost: "Included in subscription (~$15/M tokens if API)"
+    features:
+      - Full Claude capabilities
+      - No API key required
+      - Uses existing Claude login
+
+  claude-free:
+    description: "Cost-effective development using DeepSeek"
+    command: "claude-free"
+    authentication: API Key (DEEPSEEK_API_KEY)
+    cost: "~$0.14/M tokens"
+    features:
+      - Tool calling support
+      - Compatible with Claude Code workflows
+      - Project .env file support
+    setup:
+      - "Get API key at: https://platform.deepseek.com/api_keys"
+      - "Add to .env: DEEPSEEK_API_KEY=sk-your-key"
+      - "Or export: export DEEPSEEK_API_KEY=sk-your-key"
+
+configuration:
+  env_file: ".env"
+  env_variables:
+    DEEPSEEK_API_KEY:
+      description: "DeepSeek API key for claude-free command"
+      required: true
+      format: "sk-*"
+      obtain_at: "https://platform.deepseek.com/api_keys"
+
+cost_comparison:
+  claude_max:
+    input: "$15.00/M tokens"
+    output: "$75.00/M tokens"
+    note: "Included in Max subscription"
+  deepseek:
+    input: "$0.07/M tokens"
+    output: "$0.14/M tokens"
+    note: "Native Anthropic-compatible endpoint with tool support"
+
+integration:
+  wizard_step: true
+  wizard_order: 5
+  required: false
+  recommended: true
+  message: |
+    Would you like to install LLM routing commands?
+    - claude-max: Uses your Claude Max subscription
+    - claude-free: Uses DeepSeek (~99% cost reduction)
+
+health_check:
+  windows:
+    - "where claude-free.cmd"
+    - "where claude-max.cmd"
+  unix:
+    - "which claude-free"
+    - "which claude-max"
+
+troubleshooting:
+  command_not_found:
+    cause: "Commands not in PATH"
+    solution: |
+      Windows: Ensure %APPDATA%/npm is in PATH
+      Unix: Ensure /usr/local/bin or ~/bin is in PATH
+
+  api_key_error:
+    cause: "DEEPSEEK_API_KEY not set"
+    solution: |
+      1. Create .env file in project root
+      2. Add: DEEPSEEK_API_KEY=sk-your-key
+      3. Get key at: https://platform.deepseek.com/api_keys
+
+related_docs:
+  - docs/guides/llm-routing.md
+  - .aios-core/development/tasks/setup-llm-routing.md
+
+metadata:
+  created: "2025-12-14"
+  updated: "2025-12-14"
+  author: "AIOS Framework"
+  story: "6.7"