language-operator 0.1.63 → 0.1.65

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f6ed8ab896b504001c21a4886d8569ad0cf5e0fe4bfde42e22fc892ccb0a4eb
-  data.tar.gz: 449dd47813a8db16ac44f4d9ad8936590b1f4888fc5daeb1dc25fe0ed92811c4
+  metadata.gz: d7c2d32e32603ef4e3f33c04ded923e5c24d207f544a70c146034fa0d07c1f38
+  data.tar.gz: 64d778197bbcd3af3e3071db8954287912274fc9117838a8a320a8e5745956b1
 SHA512:
-  metadata.gz: 3bcf0cb1e8bf735c72ddf4b3e2a59ed0491629a9de0309207b211fe280ba80f7fcb0fb6c229330af53f20904f035207435b9d15a74628094ef2fd043f834600d
-  data.tar.gz: 262018b777c50235ccaa2654ebef86fc9d289944532e23e6ba79f1a228194c96b24f870a96a21e73bcbefd4f2dedeeba78061f458e6e360e267877c646d54ae0
+  metadata.gz: e97cd6b388ac0a8965e0be894b0e22089b3139a7cadff32979ab5920516579003e2d686933737ad55aaa4c6ff51e0ff747601702d653bbc1e755b69c307410a8
+  data.tar.gz: e28c7f2db22231bfb41c6daac57154905acd11d6ab92c683146ec0e1bbe22fd3a109cff5af501fb86f9cc80b623342b1fca956a4d3ebb51b7bc7ba618581020b

data/.plan.md

@@ -0,0 +1,127 @@
+# Implementation Plan: Fix 4 Symbolic Task Execution Test Failures
+
+## Issue Analysis
+
+Issue #121 claims "syntax errors" but the actual failures are:
+
+1. **Word count assertion error** (line 106) - Test expects 8, got 9
+2. **AST validator blocks `raise`** (line 227) - Security system rejects exception raising
+3. **Missing input type validation** (line 261) - Type validation not enforced
+4. **Missing output schema validation** (line 285) - Schema validation not enforced
+
+## Root Causes
+
+### Failure 1: Word Count Off-by-One
+- Test text: `'Hello world! This is a test. How are you?'`
+- Current split: `/\s+/` counts all whitespace-separated tokens
+- Assertion expects 8 words, actual is 9 (likely counting punctuation)
+- **Fix**: Adjust test expectation or word counting logic
+
+### Failure 2: AST Validator Blocks `raise`
+- Location: [ast_validator.rb:98](lib/language_operator/agent/safety/ast_validator.rb#L98)
+- `raise` is in DANGEROUS_METHODS list
+- Test intentionally uses `raise ArgumentError, "Cannot divide by zero"`
+- **Options**:
+  - A) Allow `raise` for standard Ruby exceptions (safe)
+  - B) Rewrite test to not use `raise` (changes test intent)
+  - **Recommendation**: Option A - `raise` is essential for error handling
+
+### Failure 3 & 4: Wrong Exception Type in Validation
+- Type/schema validation IS implemented in TaskDefinition.validate_inputs/validate_outputs
+- TypeCoercion.validate_array raises `ArgumentError: "Expected array, got String"` ✅
+- TaskDefinition.coerce_value catches and re-raises `ArgumentError` with context
+- **Problem**: Tests expect `TaskValidationError`, but code raises `ArgumentError`
+- **Fix**: TaskDefinition.coerce_value should raise `TaskValidationError` instead
+- **Location**: [lib/language_operator/dsl/task_definition.rb:279-284](lib/language_operator/dsl/task_definition.rb#L279-L284)
+
+## Investigation Plan
+
+1. ✅ Verify test failures (all 4 failures confirmed)
+2. ✅ Check AST validator - `raise` is in DANGEROUS_METHODS list
+3. ✅ Check TaskExecutor validation - calls task.validate_inputs/validate_outputs
+4. ✅ Check TypeCoercion - raises ArgumentError, not TaskValidationError
+5. ✅ Check word count - split by /\s+/ gives 9 words (punctuation attached)
+
+## Implementation Approach
+
+### Fix 1: Word Count Test (Line 106)
+**File**: spec/integration/symbolic_task_execution_spec.rb
+**Change**: Update expectation from `eq(8)` to `eq(9)`
+**Reason**: `'Hello world! This is a test. How are you?'.split(/\s+/)` produces 9 tokens
+**Tokens**: ["Hello", "world!", "This", "is", "a", "test.", "How", "are", "you?"]
+
+### Fix 2: Allow `raise` in AST Validator (Line 227)
+**File**: lib/language_operator/agent/safety/ast_validator.rb
+**Change**: Remove `raise` and `fail` from DANGEROUS_METHODS list (line 28)
+**Reason**:
+  - `raise` is essential for proper Ruby error handling
+  - Used to raise standard exceptions (ArgumentError, TypeError, etc.)
+  - Cannot escape sandbox - exceptions propagate up to agent runtime
+  - No security risk - just control flow
+**Alternative**: Could allow only standard library exceptions, but removing entirely is simpler
+
+### Fix 3 & 4: Raise TaskValidationError (Lines 261, 285)
+**File**: lib/language_operator/dsl/task_definition.rb
+**Change**: In `coerce_value` method (line 279-284), catch `ArgumentError` and raise `TaskValidationError`
+**Current**:
+```ruby
+def coerce_value(value, type, context)
+  TypeCoercion.coerce(value, type)
+rescue ArgumentError => e
+  raise ArgumentError, "#{e.message} for #{context}"
+end
+```
+**New**:
+```ruby
+def coerce_value(value, type, context)
+  TypeCoercion.coerce(value, type)
+rescue ArgumentError => e
+  raise TaskValidationError.new(@name, "#{e.message} for #{context}", e)
+end
+```
+**Impact**: Changes exception type from ArgumentError to TaskValidationError for validation failures
+
+## Files to Modify
+
+### 1. lib/language_operator/agent/safety/ast_validator.rb
+- Line 28: Remove `raise fail` from DANGEROUS_METHODS
+- Impact: Allows error handling in symbolic tasks
+
+### 2. lib/language_operator/dsl/task_definition.rb
+- Lines 279-284: Change exception type in `coerce_value` method
+- Add: `require_relative '../agent/task_executor'` at top
+- Impact: Validation errors now use correct exception class
+
+### 3. spec/integration/symbolic_task_execution_spec.rb
+- Line 106: Change `eq(8)` to `eq(9)`
+- Impact: Fixes off-by-one word count assertion
+
+## Risks & Considerations
+
+### Security - Allowing `raise`
+- **Risk**: Could `raise` be used to escape sandbox?
+  - **Analysis**: No. Exceptions propagate through call stack to agent runtime
+  - Sandbox boundary is AST validation + binding restrictions, not exception handling
+  - Standard exceptions (ArgumentError, etc.) are safe
+- **Decision**: Safe to allow. Essential for error handling.
+
+### Backward Compatibility - TaskValidationError
+- **Risk**: Existing agents may catch `ArgumentError` for validation failures
+  - **Impact**: Low - internal validation, most code doesn't catch this
+  - TaskValidationError is a subclass of TaskExecutionError (StandardError)
+  - Most exception handling uses generic `rescue` or `rescue StandardError`
+- **Decision**: Safe. Tests already expect this behavior.
+
+### Performance
+- No performance impact - only changes exception class, not validation logic
+
+## Testing Strategy
+
+1. **Fix 1** → Run test at line 106 → Should pass
+2. **Fix 2** → Run test at line 227 → Should pass
+3. **Fix 3** → Run tests at lines 261, 285 → Should pass
+4. **All fixes** → Run full integration suite
+5. **Unit tests** → Verify no regressions
+6. **Linter** → Run RuboCop
+7. **Manual test** → Create agent with symbolic task that raises exception
+# Test fixes completed

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/Gemfile

@@ -6,3 +6,5 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'pry', '~> 0.14', group: :development
+
+gem "parallel_tests", "~> 5.5", group: :development

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.63)
+    language-operator (0.1.65)
       faraday (~> 2.0)
       k8s-ruby (~> 0.17)
       lru_redux (~> 1.1)
@@ -151,6 +151,8 @@ GEM
       opentelemetry-api (~> 1.0)
     ostruct (0.6.3)
     parallel (1.27.0)
+    parallel_tests (5.5.0)
+      parallel
     parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
@@ -272,6 +274,7 @@ DEPENDENCIES
   bundler (~> 2.0)
   language-operator!
   memory_profiler (~> 1.0)
+  parallel_tests (~> 5.5)
   pry (~> 0.14)
   rack-test (~> 2.1)
   rake (~> 13.0)

data/Makefile

@@ -7,111 +7,65 @@ ITERATE_PROMPT := "/task iterate"
 PRIORITIZE_PROMPT := "/task prioritize"
 DISTILL_PROMPT := "/task distill"
 
-# Distill Claude's SCRATCH.md file
-distill:
-	@claude --dangerously-skip-permissions $(DISTILL_PROMPT)
-
-# Use claude to prioritize the backlog
-prioritize:
-	@claude --dangerously-skip-permissions $(PRIORITIZE_PROMPT)
-
-# Use claude to iterate on the backlog
-iterate:
-	@claude --dangerously-skip-permissions $(ITERATE_PROMPT)
-
-# Use claude to find bugs
-qa:
-	@claude --dangerously-skip-permissions $(QA_PROMPT)
-
-
 help: ## Show this help message
 	@echo 'Usage: make [target]'
 	@echo ''
 	@echo 'Available targets:'
-	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
 
 
-schema: ## Generate schema artifacts (JSON Schema and OpenAPI)
-	@echo "Generating schema artifacts..."
-	@bundle exec rake schema:generate
-	@echo "✅ Schema artifacts generated"
+# Claude development tasks
+# ------------------------
 
-build: schema ## Build the gem
-	@echo "Building language-operator gem..."
-	@gem build language-operator.gemspec
-	@echo "✅ Gem built successfully"
+distill: ## Distill SCRATCH.md
+	@claude --dangerously-skip-permissions $(DISTILL_PROMPT)
 
-test: ## Run the unit test suite
-	@echo "Running unit tests..."
-	@bundle exec rspec --exclude-pattern "spec/integration/**/*_spec.rb" || [ $$? -eq 1 ]
-	@echo "✅ All unit tests passed"
+prioritize: ## Prioritize the backlog and queue work
+	@claude --dangerously-skip-permissions $(PRIORITIZE_PROMPT)
 
-test-integration: ## Run integration tests for DSL v1 task execution
-	@echo "Running integration tests..."
-	@INTEGRATION_MOCK_LLM=true INTEGRATION_BENCHMARK=false bundle exec rspec spec/integration/ --tag type:integration
-	@echo "✅ All integration tests passed"
+iterate: ## Do the next right thing
+	@claude $(ITERATE_PROMPT)
 
-test-performance: ## Run performance benchmarks
-	@echo "Running performance benchmarks..."
-	@INTEGRATION_MOCK_LLM=true INTEGRATION_BENCHMARK=true bundle exec rspec spec/integration/performance_benchmarks_spec.rb --tag type:integration
-	@echo "✅ Performance benchmarks completed"
+qa: ## Find bugs and file GitHub issues
+	@claude $(QA_PROMPT)
 
-test-all: test test-integration ## Run all tests (unit + integration)
 
-install: build ## Build and install the gem locally
-	@echo "Installing gem..."
-	@gem install language-operator-*.gem
-	@echo "✅ Gem installed successfully"
+## Standard development tasks
+# ---------------------------
 
 console: ## Open an IRB console with the gem loaded
 	@bundle exec rake console
 
-docs: ## Generate YARD documentation
-	@echo "Generating documentation..."
-	@bundle exec yard doc
-	@echo "✅ Documentation generated in doc/"
+build: schema ## Build the gem
+	@gem build language-operator.gemspec
+
+install: clean build ## Build and install the gem locally
+	@gem install language-operator-*.gem
 
 lint: ## Run RuboCop linter
-	@echo "Running RuboCop..."
 	@bundle exec rubocop || [ $$? -eq 1 ]
-	@echo "✅ Linting complete"
 
-lint-fix: ## Auto-fix RuboCop issues
-	@echo "Auto-fixing RuboCop issues..."
+lint-fix: ## Run Rubocop and auto-fix issues
 	@bundle exec rubocop --autocorrect-all
 
-clean: ## Clean build artifacts
-	@echo "Cleaning build artifacts..."
-	@rm -f language-operator-*.gem
-	@rm -rf doc/
-	@rm -rf .yardoc/
-	@echo "✅ Cleaned"
-
-version-bump: ## Bump version (usage: make version-bump TYPE=patch|minor|major)
-	@if [ -z "$(TYPE)" ]; then \
-		echo "❌ Error: TYPE not specified"; \
-		echo "Usage: make version-bump TYPE=patch|minor|major"; \
-		exit 1; \
-	fi
-	@./bin/bump-version $(TYPE)
+schema: ## Generate schema artifacts (JSON Schema and OpenAPI)
+	@bundle exec rake schema:generate
 
-version-bump-patch: ## Bump patch version (0.1.0 -> 0.1.1)
-	@./bin/bump-version patch
+test: ## Run the unit test suite (use VERBOSE=1 to show all output)
+	@bundle exec rspec spec/language_operator/ --format progress
 
-version-bump-minor: ## Bump minor version (0.1.0 -> 0.2.0)
-	@./bin/bump-version minor
+test-integration: ## Run integration tests for DSL v1 task execution
+	@INTEGRATION_MOCK_LLM=true INTEGRATION_BENCHMARK=false bundle exec rspec spec/integration/ --tag type:integration
 
-version-bump-major: ## Bump major version (0.1.0 -> 1.0.0)
-	@./bin/bump-version major
+test-performance: ## Run performance benchmarks
+	@INTEGRATION_MOCK_LLM=true INTEGRATION_BENCHMARK=true bundle exec rspec spec/integration/performance_benchmarks_spec.rb --tag type:integration
 
-# CI targets
-ci-test: test test-integration lint ## Run CI test suite (unit tests + integration tests + linting)
+test-all: test test-integration ## Run all tests (unit + integration)
 
-# Development workflow
-dev-setup: ## Install development dependencies
-	@echo "Installing dependencies..."
-	@bundle install
-	@echo "✅ Development environment ready"
+yard-docs: ## Generate YARD documentation
+	@bundle exec yard doc
 
-dev-watch: ## Run tests in watch mode
-	@bundle exec guard
+clean: ## Clean build artifacts
+	@rm -f language-operator-*.gem
+	@rm -rf doc/
+	@rm -rf .yardoc/

data/components/agent/Gemfile

@@ -2,7 +2,7 @@
 
 source 'https://rubygems.org'
 
-gem 'language-operator', '~> 0.1.63'
+gem 'language-operator', '~> 0.1.65', path: '../..'
 
 # Agent-specific dependencies for autonomous execution
 gem 'concurrent-ruby', '~> 1.3'

data/docs/cheat-sheet.md

@@ -0,0 +1,173 @@
+# aictl Cheat Sheet
+
+Quick reference for the `aictl` command-line interface.
+
+## General Commands
+
+```bash
+aictl --help                          # Show general help
+aictl version                         # Display aictl and operator version information  
+aictl status                          # Show system status and cluster overview
+aictl quickstart                      # Launch interactive setup wizard for first-time users
+aictl completion bash                 # Install bash shell completions
+aictl completion zsh                  # Install zsh shell completions
+aictl completion fish                 # Install fish shell completions
+```
+
+## Cluster Management
+
+```bash
+aictl cluster create <name>           # Create a new language cluster
+aictl cluster list                    # List all configured clusters
+aictl cluster current                 # Show current active cluster
+aictl cluster inspect <name>          # Show detailed cluster information
+aictl cluster delete <name>           # Delete a cluster
+aictl use <cluster>                   # Switch to a different cluster
+```
+
+## Agent Management  
+
+```bash
+aictl agent create "<description>"    # Create agent from natural language description
+aictl agent create --wizard           # Create agent using interactive wizard
+aictl agent list                      # List all agents in current cluster
+aictl agent inspect <name>            # Show detailed agent information
+aictl agent delete <name>             # Delete an agent
+aictl agent versions <name>           # Show ConfigMap versions for agent learning history
+```
+
+## Agent Operations
+
+```bash
+aictl agent logs <name>               # View agent execution logs
+aictl agent logs <name> -f            # Follow agent logs in real-time  
+aictl agent code <name>               # Show synthesized agent code
+aictl agent workspace <name>          # Access agent's persistent workspace
+aictl agent learning status <name>    # Show agent learning optimization status
+aictl agent learning enable <name>    # Enable automatic learning for agent
+aictl agent learning disable <name>   # Disable automatic learning for agent
+```
+
+## Model Management
+
+```bash
+aictl model create <name>             # Create model using interactive wizard
+aictl model create <name> --provider openai --model gpt-4  # Create model with specific config
+aictl model list                      # List all available models
+aictl model inspect <name>            # Show detailed model information
+aictl model delete <name>             # Delete a model
+aictl model edit <name>               # Edit model configuration in YAML
+aictl model test <name>               # Test model connectivity and basic functionality
+```
+
+## Tool Management
+
+```bash
+aictl tool install <name>             # Install a tool from registry
+aictl tool search <query>             # Search available tools in registry
+aictl tool list                       # List installed tools
+aictl tool inspect <name>             # Show detailed tool information and MCP capabilities
+aictl tool delete <name>              # Delete a tool
+aictl tool test <name>                # Test tool health and connectivity
+```
+
+## Persona Management
+
+```bash
+aictl persona create <name>           # Create persona using interactive editor
+aictl persona create <name> --from <existing>  # Create persona based on existing one
+aictl persona list                    # List all available personas
+aictl persona show <name>             # Display full persona details and system prompt
+aictl persona edit <name>             # Edit persona definition in YAML editor
+aictl persona delete <name>           # Delete a persona
+```
+
+## Installation & Deployment
+
+```bash
+aictl install                         # Install language-operator to cluster using Helm
+aictl install --dry-run               # Preview installation without applying changes
+aictl upgrade                         # Upgrade existing operator installation
+aictl uninstall                       # Remove operator from cluster
+```
+
+## System Utilities
+
+```bash
+aictl system schema                   # Display current DSL JSON schema
+aictl system validate-template <file> # Validate agent template file syntax
+aictl system synthesize <template>    # Synthesize agent code from template
+aictl system synthesis-template <name> # Show synthesis template used for agent
+aictl system exec <agent> -- <cmd>    # Execute command inside agent pod
+```
+
+## Common Options
+
+All commands support these common options:
+
+```bash
+--cluster <name>                      # Override current cluster context
+--dry-run                             # Preview changes without applying
+--force                               # Skip confirmation prompts
+--help                                # Show command-specific help
+```
+
+## Examples
+
+### Quick Start
+```bash
+# First-time setup
+aictl quickstart                      # Interactive setup wizard
+aictl install                         # Install operator to cluster
+aictl cluster create production       # Create your first cluster
+
+# Create and deploy an agent
+aictl agent create "monitor my website and alert me if it goes down"
+```
+
+### Daily Operations
+```bash
+# Check system status
+aictl status                          # Overview of cluster and resources
+aictl agent list                      # See all running agents
+aictl agent logs my-agent -f          # Monitor agent activity
+
+# Manage resources
+aictl model list                      # Available AI models
+aictl tool install github             # Add new capabilities
+aictl persona create helper --from technical-writer  # Customize agent personalities
+```
+
+### Development & Debugging
+```bash
+# Inspect resources  
+aictl agent inspect my-agent          # Detailed agent status and configuration
+aictl agent code my-agent             # View synthesized code
+aictl agent workspace my-agent        # Access persistent data
+
+# Troubleshooting
+aictl model test gpt-4                # Verify model connectivity
+aictl tool test github                # Check tool health
+aictl system validate-template agent.yaml  # Validate configuration files
+```
+
+### Multi-Cluster Management
+```bash
+# Working with multiple environments
+aictl cluster create staging
+aictl cluster create production  
+aictl use staging                      # Switch contexts
+aictl agent list --all-clusters       # View agents across all clusters
+```
+
+## Quick Tips
+
+- Use `--dry-run` to preview changes before applying them
+- Add `--help` to any command for detailed usage information
+- Agent descriptions in quotes support natural language
+- Use `--wizard` flag for interactive guidance on complex operations
+- Commands auto-complete with shell completions installed
+
+---
+
+For complete documentation, see: [Language Operator Documentation](../README.md)

data/lib/language_operator/agent/base.rb

@@ -2,6 +2,7 @@
 
 require_relative '../client'
 require_relative '../constants'
+require_relative '../kubernetes/client'
 require_relative 'telemetry'
 require_relative 'instrumentation'
 
@@ -21,7 +22,7 @@ module LanguageOperator
     class Base < LanguageOperator::Client::Base
       include Instrumentation
 
-      attr_reader :workspace_path, :mode
+      attr_reader :workspace_path, :mode, :kubernetes_client
 
       # Initialize the agent
       #
@@ -40,6 +41,14 @@ module LanguageOperator
         @workspace_path = ENV.fetch('WORKSPACE_PATH', '/workspace')
         @mode = agent_mode_with_default
         @executor = nil
+
+        # Initialize Kubernetes client for event emission (only in K8s environments)
+        @kubernetes_client = begin
+          LanguageOperator::Kubernetes::Client.instance if ENV.fetch('KUBERNETES_SERVICE_HOST', nil)
+        rescue StandardError => e
+          logger.warn('Failed to initialize Kubernetes client', error: e.message)
+          nil
+        end
       end
 
       # Run the agent in its configured mode