diff options
| -rw-r--r-- | .github/workflows/release.yml | 38 | ||||
| -rw-r--r-- | docs/research/claude-flow-research.md | 169 | ||||
| -rw-r--r-- | docs/research/makima-improvement-ideas.md | 228 | ||||
| -rw-r--r-- | docs/research/ruvector-research.md | 113 | ||||
| -rw-r--r-- | makima/src/bin/makima.rs | 52 | ||||
| -rw-r--r-- | makima/src/daemon/api/supervisor.rs | 31 | ||||
| -rw-r--r-- | makima/src/daemon/cli/directive.rs | 27 | ||||
| -rw-r--r-- | makima/src/daemon/cli/mod.rs | 3 | ||||
| -rw-r--r-- | makima/src/daemon/skills/directive.md | 27 | ||||
| -rw-r--r-- | makima/src/orchestration/directive.rs | 20 | ||||
| -rw-r--r-- | makima/src/server/handlers/mesh_supervisor.rs | 309 | ||||
| -rw-r--r-- | makima/src/server/mod.rs | 3 | ||||
| -rw-r--r-- | makima/src/server/state.rs | 5 |
13 files changed, 981 insertions, 44 deletions
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0bcd8dc..7a8a865 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -24,10 +24,6 @@ jobs: os: macos-15-intel artifact_name: makima asset_name: makima-${{ github.ref_name }}-macos-x86_64 - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - artifact_name: makima - asset_name: makima-${{ github.ref_name }}-linux-arm64 - target: aarch64-apple-darwin os: macos-14 artifact_name: makima @@ -48,23 +44,6 @@ jobs: sudo apt-get update sudo apt-get install -y pkg-config libssl-dev - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo dpkg --add-architecture arm64 - # Add ports.ubuntu.com source for arm64 packages - sudo tee /etc/apt/sources.list.d/arm64-ports.list <<PORTS - deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports/ $(lsb_release -cs) main restricted universe - deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports/ $(lsb_release -cs)-updates main restricted universe - deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports/ $(lsb_release -cs)-security main restricted universe - PORTS - # Pin default sources to amd64 only so they don't conflict - sudo sed -i 's/^deb /deb [arch=amd64] /' /etc/apt/sources.list /etc/apt/sources.list.d/ubuntu.sources 2>/dev/null || true - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu libssl-dev:arm64 - echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV - echo "PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu" >> $GITHUB_ENV - - name: Build release binary working-directory: makima run: cargo build --release --target ${{ matrix.target }} @@ -97,12 +76,6 @@ jobs: name: makima-${{ github.ref_name }}-linux-x86_64 path: daemon-binaries - - name: Download Linux ARM64 artifact - uses: actions/download-artifact@v4 - with: - name: makima-${{ github.ref_name }}-linux-arm64 - path: daemon-binaries - - name: Download macOS ARM64 artifact uses: actions/download-artifact@v4 with: @@ -111,10 +84,9 @@ jobs: - name: Extract and repackage daemon binaries run: | - mkdir -p daemon-extracted/linux-x86_64 daemon-extracted/linux-arm64 daemon-extracted/macos-arm64 + mkdir -p daemon-extracted/linux-x86_64 daemon-extracted/macos-arm64 tar xzf daemon-binaries/makima-${{ github.ref_name }}-linux-x86_64.tar.gz -C daemon-extracted/linux-x86_64 - tar xzf daemon-binaries/makima-${{ github.ref_name }}-linux-arm64.tar.gz -C daemon-extracted/linux-arm64 tar xzf daemon-binaries/makima-${{ github.ref_name }}-macos-arm64.tar.gz -C daemon-extracted/macos-arm64 tar czvf daemon-binaries.tar.gz -C daemon-extracted . @@ -170,10 +142,6 @@ jobs: curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-linux-x86_64.tar.gz | tar xzf - chmod +x makima && sudo mv makima /usr/local/bin/ - # Linux ARM64 - curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-linux-arm64.tar.gz | tar xzf - - chmod +x makima && sudo mv makima /usr/local/bin/ - # macOS Intel curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-macos-x86_64.tar.gz | tar xzf - chmod +x makima && sudo mv makima /usr/local/bin/ @@ -221,10 +189,6 @@ jobs: curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-linux-x86_64.tar.gz | tar xzf - chmod +x makima && sudo mv makima /usr/local/bin/ - # Linux ARM64 - curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-linux-arm64.tar.gz | tar xzf - - chmod +x makima && sudo mv makima /usr/local/bin/ - # macOS Intel curl -fsSL https://github.com/soryu-co/makima/releases/download/${{ github.ref_name }}/makima-${{ github.ref_name }}-macos-x86_64.tar.gz | tar xzf - chmod +x makima && sudo mv makima /usr/local/bin/ diff --git a/docs/research/claude-flow-research.md b/docs/research/claude-flow-research.md new file mode 100644 index 0000000..479691a --- /dev/null +++ b/docs/research/claude-flow-research.md @@ -0,0 +1,169 @@ +# Claude-Flow (Ruflo v3) Research Summary + +> Research conducted 2026-02-24 for makima improvement evaluation + +## Overview + +claude-flow (marketed as Ruflo v3) is an enterprise AI orchestration system built around Claude Code. It provides 175+ MCP tools, manages 60+ specialized agents, and has accumulated 5,923+ commits. Key performance claims: 84.8% SWE-Bench solve rate, 2.8-4.4x faster task completion vs baseline Claude Code. + +**Repository**: https://github.com/ruvnet/claude-flow + +## Architecture + +### Layered Design +``` +User Layer: CLI + Claude Code interfaces +Entry Layer: MCP Server with AIDefence security validation +Routing Layer: Q-Learning router + MoE (8 experts) + 42 skills + 17 hooks +Swarm Layer: Topologies (mesh/hierarchical/ring/star) + consensus +Agent Layer: 60+ specialized agents +Resources: Memory systems, LLM providers, 12 background workers +Intelligence: RuVector with 10+ optimization components +``` + +### MCP Integration +- Runs as stdio process providing 175+ tools +- MCP 2025-11-25 full specification compliance +- Supports tools, resources, prompts, and tasks +- Multiple transports: stdio, HTTP, WebSocket, in-process + +## Multi-Agent Coordination (Hive Mind) + +### Queen Types (Coordinators) +| Type | Role | +|------|------| +| Strategic | Planning and goal decomposition | +| Tactical | Execution coordination | +| Adaptive | Optimization and learning | + +### Worker Types (8 Specialized Roles) +1. **Researcher** - Information gathering and analysis +2. **Coder** - Implementation +3. **Analyst** - Data analysis and insights +4. **Tester** - Quality assurance +5. **Architect** - System design +6. **Reviewer** - Code review and quality gates +7. **Optimizer** - Performance tuning +8. **Documenter** - Documentation generation + +### Consensus Algorithms +- **Byzantine** (f < n/3): 2/3 majority for decisions +- **Weighted Voting**: Queen has 3x authority +- **Majority Voting**: Simple democratic decisions + +## Task Routing & Scheduling + +### Q-Learning Router +- Combined with MoE (8 experts) +- 89% routing accuracy +- 34,798 routes/s throughput +- Learns which agents perform best per task type through execution trajectories + +### Three-Tier Routing Strategy +| Tier | Handler | Latency | Cost | +|------|---------|---------|------| +| Simple | Agent Booster WASM | <1ms | $0 | +| Medium | Haiku/Sonnet | ~500ms | Low | +| Complex | Opus + multi-agent swarms | 2-5s | Standard | + +### Task Templates (Agent Combinations) +| Task Type | Recommended Agents | +|-----------|--------------------| +| Bug Fix | Coordinator, Researcher, Coder, Tester | +| Feature | Coordinator, Architect, Coder, Tester, Reviewer | +| Refactor | Coordinator, Architect, Coder, Reviewer | +| Performance | Coordinator, Perf-Engineer, Coder | +| Security | Coordinator, Security-Architect, Auditor | + +## Self-Learning Mechanisms + +### SONA (Self-Optimizing Neural Architecture) +- <0.05ms adaptation time +- Rapid behavior adjustment at runtime +- Two-tier LoRA + EWC++ + ReasoningBank integration + +### EWC++ (Elastic Weight Consolidation) +- Preserves 95%+ knowledge across tasks +- Prevents catastrophic forgetting + +### ReasoningBank +- Pattern caching with RETRIEVE → JUDGE → DISTILL → CONSOLIDATE → ROUTE cycle +- 32% token savings through pattern retrieval instead of full context +- Stores successful execution trajectories for reuse + +### MicroLoRA +- 128x compressed fine-tuning +- No full retraining required +- Lightweight runtime adaptation + +## Memory & Context Sharing + +### 3-Scope Architecture +| Scope | Purpose | +|-------|---------| +| Project | Task-specific context | +| Local | Machine/user patterns | +| User | Cross-project learnings | + +### Storage Stack +- **HNSW Vector Search**: 150x-12,500x faster retrieval, 16,400 QPS +- **AgentDB**: SQLite with WAL for persistence +- **LRU Cache**: Sub-millisecond access for hot data +- **Knowledge Graph**: PageRank + community detection for insight ranking + +### 8 Memory Types +Attention, episodic, procedural, semantic, + 4 additional types for comprehensive knowledge representation. + +## Drift Control + +Critical for multi-agent alignment: +1. **Hierarchical Coordinator** validates all outputs against goals +2. **Small Teams** (6-8 agents) reduce coordination overhead +3. **Frequent Checkpoints** via post-task hooks verify compliance +4. **Raft Consensus** maintains authoritative state +5. **Specialized Roles** enforce clear task boundaries + +## Cost Optimization + +### Multi-Layer Strategy +| Layer | Mechanism | Savings | +|-------|-----------|---------| +| 1 | Agent Booster WASM | Eliminates tokens entirely | +| 2 | Haiku/Sonnet routing | 75% lower than Opus | +| 3 | ReasoningBank | -32% token savings | +| 4 | Token compression | 30-50% reduction | +| 5 | Caching | 95% hit rate | +| **Combined** | **All layers** | **Extends Claude Max 250%** | + +## Hook System + +33+ hooks across 7 categories: +- **Session**: start, end +- **Agent**: pre-spawn, post-spawn, pre-terminate +- **Task**: pre-execute, post-complete, error +- **Tool**: pre-call, post-call +- **Memory**: store/retrieve operations +- **Swarm**: coordination events +- **File**: read/write operations + +Self-Learning Hooks feed execution insights back into the Q-Learning router. + +## Claims System (Human-Agent Coordination) +- **Claim**: Agent requests task ownership +- **Release**: Agent returns uncompleted work +- **Handoff**: Human reassigns to different agent +- Prevents duplicate effort and maintains clear responsibility + +## Fault Tolerance +- Byzantine fault-tolerant (f < n/3, 2/3 majority) +- 6 LLM provider failover (Claude, GPT, Gemini, etc.) +- Checkpoint system prevents cascading failures +- Persist/Restore/Export session management + +## Swarm Topologies +| Topology | Structure | Best For | +|----------|-----------|----------| +| Hierarchical | Coordinator + workers | Structured coding tasks (0.20s, 256MB/agent) | +| Mesh | Peer-to-peer | Collaborative, high redundancy | +| Ring | Sequential chain | Pipeline processing | +| Star | Hub-and-spoke | Centralized control | diff --git a/docs/research/makima-improvement-ideas.md b/docs/research/makima-improvement-ideas.md new file mode 100644 index 0000000..36e3be2 --- /dev/null +++ b/docs/research/makima-improvement-ideas.md @@ -0,0 +1,228 @@ +# Makima Improvement Ideas from claude-flow & ruvector Research + +> Research conducted 2026-02-24 +> Sources: https://github.com/ruvnet/claude-flow, https://github.com/ruvnet/ruvector + +## Summary of Top Improvement Ideas + +### 1. Intelligent Task Routing with Q-Learning +**Source**: claude-flow Q-Learning Router + MoE +**Priority**: High +**Type**: Spike + +**Current State**: Makima uses static task assignment - the planning step determines task distribution upfront. + +**Improvement**: Add a Q-Learning-based router that learns which types of tasks succeed best with which configurations. Track execution metrics (time, token usage, success rate, retry count) per task type and use this to inform future planning. + +**Implementation Sketch**: +- Record task execution telemetry (duration, tokens, outcome, complexity indicators) +- Build a task-type classifier based on step descriptions +- Train Q-values for (task_type, configuration) → expected_outcome +- Use learned routing to suggest optimal task configurations during directive planning +- Start simple: just track success rates by task description keywords + +**Expected Benefit**: 20-40% improvement in task completion rates, reduced wasted retries. + +--- + +### 2. Self-Learning from Execution Trajectories (ReasoningBank) +**Source**: claude-flow ReasoningBank, ruvector trajectory learning +**Priority**: High +**Type**: Spike + +**Current State**: Makima doesn't learn from past executions. Each new directive starts from scratch. + +**Improvement**: Implement a pattern bank that stores successful task plans, common failure patterns, and effective prompt strategies. When planning new directives, retrieve similar past successes to inform the plan. + +**Implementation Sketch**: +- After each directive completes, extract and store: step descriptions, task plans, success/failure, duration, key decisions +- Use embedding similarity (via simple TF-IDF or external embeddings) to match new steps against past patterns +- Inject relevant past patterns into the planning prompt as examples +- Track which patterns led to better outcomes (RETRIEVE → JUDGE → CONSOLIDATE cycle) + +**Expected Benefit**: 30%+ faster planning, fewer failed first attempts, accumulated organizational knowledge. + +--- + +### 3. Drift Control & Checkpoint System +**Source**: claude-flow anti-drift mechanisms +**Priority**: High +**Type**: Spike + +**Current State**: Makima relies on Claude Code to stay on-task. No systematic drift detection. + +**Improvement**: Add checkpoint validation between task steps. The coordinator can review task outputs against original goals and catch drift early. + +**Implementation Sketch**: +- Add post-task hooks that validate output against step description +- Implement a lightweight "alignment check" prompt that evaluates: "Does this output match the intended goal?" +- If drift detected, flag for human review (reconcile mode) or auto-correct +- Track drift frequency per task type to improve future task plans + +**Expected Benefit**: Catch 80%+ of drift before it compounds across steps. Reduce wasted work. + +--- + +### 4. Cost-Aware Model Routing +**Source**: claude-flow three-tier routing, Agent Booster +**Priority**: Medium +**Type**: Spike + +**Current State**: Makima always uses whatever Claude Code instance is configured. No cost optimization. + +**Improvement**: Classify task complexity and route to appropriate model tier. Simple tasks (documentation updates, config changes) could use cheaper models or cached patterns. Complex tasks (architecture, debugging) get full Opus. + +**Implementation Sketch**: +- Add task complexity classifier based on description keywords and historical data +- For simple tasks: use Haiku-class model or pre-cached patterns +- For medium tasks: use Sonnet +- For complex tasks: use Opus with extended context +- Track cost per task and optimize routing over time + +**Expected Benefit**: 40-60% cost reduction for typical directive workloads. + +--- + +### 5. Hook/Event System for Task Lifecycle +**Source**: claude-flow 33+ hook system +**Priority**: Medium +**Type**: Spike + +**Current State**: Makima has limited lifecycle events. Steps go from pending → running → completed/failed. + +**Improvement**: Add a hook/event system for extensible task lifecycle management. Events like pre-task, post-task, on-error, on-retry enable plugins for logging, metrics, drift detection, and custom workflows. + +**Implementation Sketch**: +- Define event types: directive.start, step.start, step.complete, step.fail, step.retry, task.spawn, task.complete +- Add webhook/callback support for each event +- Enable custom handlers (e.g., Slack notifications, metrics collection, auto-retry policies) +- Use events to feed the self-learning system + +**Expected Benefit**: Extensibility, better observability, foundation for self-learning and drift control. + +--- + +### 6. Swarm Topologies for Complex Directives +**Source**: claude-flow swarm coordination (hierarchical, mesh, ring, star) +**Priority**: Medium +**Type**: Spike + +**Current State**: Makima uses a simple supervisor → worker model. + +**Improvement**: Support different coordination topologies for different directive types. Large features could use hierarchical (coordinator reviews all outputs). Research tasks could use mesh (agents share findings). Sequential migrations could use ring (output chains). + +**Implementation Sketch**: +- Define topology types in directive configuration +- Hierarchical: one coordinator task validates all worker outputs before proceeding +- Mesh: tasks can share intermediate results through shared files/context +- Ring: strict sequential with output-as-input chaining +- Auto-select topology based on directive type + +**Expected Benefit**: Better coordination for complex multi-task directives. Reduced duplication and conflict. + +--- + +### 7. Self-Learning DAG Optimization +**Source**: ruvector self-learning DAG execution +**Priority**: Medium +**Type**: Spike + +**Current State**: Makima DAG execution follows static dependency ordering. + +**Improvement**: Learn optimal step ordering and parallelization from execution history. Identify which steps benefit from parallelization vs sequential execution. Automatically adjust DAG scheduling based on learned patterns. + +**Implementation Sketch**: +- Track actual execution times and dependencies between steps +- Identify critical path and bottleneck steps +- Learn which steps can safely run in parallel (based on file overlap analysis) +- Apply MinCut-style optimization to identify steps that could be split for parallelism +- Suggest DAG modifications during planning based on historical data + +**Expected Benefit**: 20-40% faster directive completion through optimized scheduling. + +--- + +### 8. Memory/Context Sharing Between Tasks +**Source**: claude-flow 3-scope memory, ruvector COW branching +**Priority**: Medium +**Type**: Spike + +**Current State**: Each makima task operates in isolation with its own worktree. Limited context sharing. + +**Improvement**: Implement scoped shared memory for cross-task context sharing. Tasks within the same directive should be able to share findings, decisions, and intermediate results. + +**Implementation Sketch**: +- Add directive-scoped key-value store (the `memory-set`/`memory-get` commands from the task plan) +- Tasks can read/write to shared directive memory +- Support structured data (JSON) for machine-readable sharing +- Add project-scoped memory for cross-directive learnings +- Consider copy-on-write semantics for large shared contexts + +**Expected Benefit**: Better coordination between parallel tasks. Reduced redundant work. + +--- + +### 9. Claims System for Human-Agent Coordination +**Source**: claude-flow claims system +**Priority**: Low +**Type**: Chore + +**Current State**: Makima reconcile mode allows human review but lacks formal work ownership tracking. + +**Improvement**: Add a claims system where tasks can be claimed by agents or humans. Enables smooth handoff when an agent gets stuck and a human needs to take over (or vice versa). + +**Implementation Sketch**: +- Add claim/release/handoff operations to task lifecycle +- Track who (agent or human) currently owns each task +- Allow partial completion with handoff notes +- Integrate with reconcile mode for approval workflows + +**Expected Benefit**: Smoother human-agent collaboration. Clearer responsibility tracking. + +--- + +### 10. Fault Tolerance with Provider Failover +**Source**: claude-flow 6-provider failover, ruvector Raft consensus +**Priority**: Low +**Type**: Spike + +**Current State**: Makima depends on a single Claude Code provider. Failures require manual intervention. + +**Improvement**: Add retry policies with exponential backoff, provider failover (if multiple API keys available), and graceful degradation. + +**Implementation Sketch**: +- Add configurable retry policies per task type +- Support multiple API key rotation +- Implement circuit breaker pattern for persistent failures +- Auto-reassign failed tasks to fresh Claude Code instances +- Track failure patterns to avoid repeating known-bad configurations + +**Expected Benefit**: Higher reliability. Reduced manual intervention for transient failures. + +--- + +## Priority Matrix + +| # | Improvement | Impact | Effort | Priority | +|---|-------------|--------|--------|----------| +| 1 | Q-Learning Task Routing | High | High | High | +| 2 | ReasoningBank (Learn from History) | High | Medium | High | +| 3 | Drift Control & Checkpoints | High | Medium | High | +| 4 | Cost-Aware Model Routing | Medium | Medium | Medium | +| 5 | Hook/Event System | Medium | Medium | Medium | +| 6 | Swarm Topologies | Medium | High | Medium | +| 7 | Self-Learning DAG Optimization | Medium | High | Medium | +| 8 | Memory/Context Sharing | Medium | Medium | Medium | +| 9 | Claims System | Low | Low | Low | +| 10 | Fault Tolerance/Failover | Low | Medium | Low | + +## Quick Wins (Implement First) + +1. **Execution telemetry** - Start recording task metrics now (foundation for everything) +2. **Directive memory** (`memory-set`/`memory-get`) - Already planned, enables context sharing +3. **Post-task validation** - Simple alignment check on completed tasks +4. **Retry policies** - Configurable auto-retry with backoff + +## Long-Term Vision + +Combine items 1, 2, 7 into a **Self-Improving Orchestration Engine**: makima learns from every directive execution, optimizes task routing and scheduling, and continuously improves planning quality. This creates a competitive moat where the system gets better with every use. diff --git a/docs/research/ruvector-research.md b/docs/research/ruvector-research.md new file mode 100644 index 0000000..faf00d0 --- /dev/null +++ b/docs/research/ruvector-research.md @@ -0,0 +1,113 @@ +# RuVector Research Summary + +> Research conducted 2026-02-24 for makima improvement evaluation + +## Overview + +RuVector is a high-performance vector database with graph intelligence capabilities, self-learning DAG execution, and distributed consensus. It combines vector search, graph neural networks, and reinforcement learning into a unified platform. + +**Repository**: https://github.com/ruvnet/ruvector + +## Architecture + +### Core Components +- **HNSW Indexing**: Hierarchical Navigable Small World for approximate nearest neighbor search +- **GNN Layers**: Graph Neural Networks for query reranking and path optimization +- **ReasoningBank**: Trajectory learning with verdict judgment +- **SONA**: Self-Optimizing Neural Architecture for runtime adaptation +- **Raft Consensus**: Distributed coordination and fault tolerance + +### Key Performance +- 61µs p50 latency for vector queries +- 2-32x memory reduction via adaptive compression +- SIMD acceleration (AVX2/AVX-512/NEON) +- 10-50x burst scaling for traffic spikes + +## Graph Database Capabilities + +### Cypher Query Support +- Neo4j-compatible Cypher syntax: `MATCH (a)-[:SIMILAR]->(b)` +- Hyperedge support connecting 3+ nodes simultaneously +- Combines relationship-based search with vector similarity +- Enables "semantic + structured search" + +### Graph Intelligence +- PageRank computation +- Spectral clustering +- Community detection +- Multi-head attention for neighbor importance weighting + +## Self-Learning DAG Execution + +This is the most relevant capability for makima: + +### Architecture +- **Automatic query optimization** through continuous learning +- **7 attention mechanisms** dynamically select optimal execution strategies +- **50-80% latency reduction** over time as patterns are learned +- **MinCut control** triggers automatic strategy switching above tension thresholds + +### Learning Cycle +1. **Topological analysis** of DAG structure +2. **Causal cone evaluation** for dependency impact +3. **Critical path identification** and optimization +4. **Trajectory learning** via ReasoningBank +5. **Adaptive routing** based on learned patterns + +## Self-Learning Mechanisms + +### SONA (Self-Optimizing Neural Architecture) +- Two-tier LoRA + EWC++ + ReasoningBank +- <1ms adaptive learning per request +- 55% quality improvement over baseline +- Per-request micro-LoRA adaptation (rank 1-2) + +### GNN-Based Optimization +- Multi-head attention weights neighbor importance +- Updates representations based on graph structure +- Reinforces frequently-accessed paths +- "The more you search, the better results get" + +### Q-Learning Integration +- Neural patterns learn optimal routing +- HNSW memory integration for fast retrieval +- Dynamic index topology optimization + +## Memory Management + +### Efficiency Mechanisms +- **Adaptive tiered compression**: 2-32x memory reduction +- **SIMD-optimized SpMV**: Sparse matrix-vector multiplication +- **Arena allocators**: Bounds-check elimination +- **COW branching**: Cluster-level copy-on-write (1M vectors, ~2.5MB per edit) + +### RVF Cognitive Container +- Git-like branching of vector datasets +- DNA-style lineage tracking parent/child derivation +- Cryptographic verification of data integrity +- Progressive indexing through layered construction + +## Fault Tolerance + +- **Raft consensus**: Leader election and log replication +- **Multi-master replication**: Vector clock conflict resolution +- **Geo-distributed sync**: Cross-region high availability +- **Snapshot/backup**: Point-in-time recovery +- **Post-quantum signatures**: ML-DSA-65 and Ed25519 on every segment + +## Advanced Features + +### 46 Attention Mechanisms +Categories: standard (dot-product, multi-head, Flash), graph-specific (RoPE, edge-featured, dual-space), efficiency (sparse, cross-attention, neighborhood), specialized (mincut-gated transformer with 50% compute reduction). + +### Adaptive Routing +- "Tiny Dancer" FastGRNN neural inference +- 90% semantic routing accuracy +- Hybrid keyword-first + embedding fallback strategy + +### Additional Capabilities +- Local LLM execution (ruvllm with GGUF models) +- Topological data analysis via persistent homology +- Post-quantum cryptography +- eBPF kernel acceleration +- 5.5KB WASM runtime for browser deployment diff --git a/makima/src/bin/makima.rs b/makima/src/bin/makima.rs index aaf5a08..c4183f3 100644 --- a/makima/src/bin/makima.rs +++ b/makima/src/bin/makima.rs @@ -810,6 +810,58 @@ async fn run_directive( let result = client .supervisor_ask(&args.question, choices, args.context, args.timeout, args.phaseguard, args.multi_select, args.non_blocking, args.question_type) .await?; + let mut response_value = result.0; + + // If the server returned still_pending, poll until we get a real response + while response_value.get("stillPending").and_then(|v| v.as_bool()).unwrap_or(false) { + // Extract question_id for polling + let question_id_str = response_value.get("questionId") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + Box::<dyn std::error::Error + Send + Sync>::from( + "Missing questionId in still_pending response" + ) + })?; + let question_id: uuid::Uuid = question_id_str.parse().map_err(|e| { + Box::<dyn std::error::Error + Send + Sync>::from( + format!("Invalid questionId: {}", e) + ) + })?; + + eprintln!("Waiting for user response (polling)..."); + let poll_result = client.supervisor_poll_question(question_id).await?; + response_value = poll_result.0; + } + + println!("{}", serde_json::to_string(&response_value)?); + } + DirectiveCommand::CreateOrder(args) => { + // Validate order_type is spike or chore + if args.order_type != "spike" && args.order_type != "chore" { + eprintln!("Error: Only 'spike' and 'chore' order types are allowed. Got: '{}'", args.order_type); + std::process::exit(1); + } + let client = ApiClient::new(args.common.api_url.clone(), args.common.api_key.clone())?; + eprintln!("Creating order: {}...", args.title); + let labels = args + .labels + .map(|l| { + serde_json::Value::Array( + l.split(',') + .map(|s| serde_json::Value::String(s.trim().to_string())) + .collect(), + ) + }) + .unwrap_or_else(|| serde_json::json!([])); + let req = makima::daemon::api::supervisor::CreateOrderRequest { + title: args.title, + description: args.description, + priority: args.priority, + order_type: args.order_type, + labels, + repository_url: None, + }; + let result = client.create_order(&req).await?; println!("{}", serde_json::to_string(&result.0)?); } } diff --git a/makima/src/daemon/api/supervisor.rs b/makima/src/daemon/api/supervisor.rs index c67c9ca..675b0bb 100644 --- a/makima/src/daemon/api/supervisor.rs +++ b/makima/src/daemon/api/supervisor.rs @@ -83,6 +83,20 @@ pub struct AskQuestionRequest { pub question_type: String, } +/// Request to create an order for future work. +#[derive(Serialize)] +#[serde(rename_all = "camelCase")] +pub struct CreateOrderRequest { + pub title: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub description: Option<String>, + pub priority: String, + pub order_type: String, + pub labels: serde_json::Value, + #[serde(skip_serializing_if = "Option::is_none")] + pub repository_url: Option<String>, +} + // Generic response type for JSON output #[derive(Deserialize, Serialize)] pub struct JsonValue(pub serde_json::Value); @@ -228,6 +242,18 @@ impl ApiClient { self.post("/api/v1/mesh/supervisor/questions", &req).await } + /// Poll for a question response by question_id. + /// + /// Used after a still_pending response from supervisor_ask. Blocks for up to + /// 5 minutes on the server side. Returns still_pending if no response yet. + pub async fn supervisor_poll_question( + &self, + question_id: Uuid, + ) -> Result<JsonValue, ApiError> { + self.get(&format!("/api/v1/mesh/supervisor/questions/{}/poll", question_id)) + .await + } + /// Advance contract to a new phase. /// /// When `confirmed` is false and phase_guard is enabled, returns a response with @@ -312,6 +338,11 @@ impl ApiClient { .await } + /// Create an order for future work from a directive task. + pub async fn create_order(&self, req: &CreateOrderRequest) -> Result<JsonValue, ApiError> { + self.post("/api/v1/mesh/supervisor/orders", req).await + } + /// Delete a task. pub async fn delete_task(&self, task_id: Uuid) -> Result<(), ApiError> { self.delete(&format!("/api/v1/mesh/tasks/{}", task_id)).await diff --git a/makima/src/daemon/cli/directive.rs b/makima/src/daemon/cli/directive.rs index 7c8451f..cc7b224 100644 --- a/makima/src/daemon/cli/directive.rs +++ b/makima/src/daemon/cli/directive.rs @@ -150,6 +150,33 @@ pub struct AskArgs { pub question_type: String, } +/// Arguments for create-order command. +#[derive(Args, Debug)] +pub struct CreateOrderArgs { + #[command(flatten)] + pub common: DirectiveArgs, + + /// Order title + #[arg(long)] + pub title: String, + + /// Order description + #[arg(long)] + pub description: Option<String>, + + /// Priority: critical, high, medium, low, none + #[arg(long, default_value = "medium")] + pub priority: String, + + /// Order type: spike or chore only + #[arg(long, default_value = "spike")] + pub order_type: String, + + /// Comma-separated labels + #[arg(long)] + pub labels: Option<String>, +} + /// Arguments for update command. #[derive(Args, Debug)] pub struct UpdateArgs { diff --git a/makima/src/daemon/cli/mod.rs b/makima/src/daemon/cli/mod.rs index 8063541..af6f885 100644 --- a/makima/src/daemon/cli/mod.rs +++ b/makima/src/daemon/cli/mod.rs @@ -252,6 +252,9 @@ pub enum DirectiveCommand { /// Ask a question and wait for user feedback Ask(directive::AskArgs), + + /// Create an order for future work (spike or chore only) + CreateOrder(directive::CreateOrderArgs), } impl Cli { diff --git a/makima/src/daemon/skills/directive.md b/makima/src/daemon/skills/directive.md index 02de836..dc1bce2 100644 --- a/makima/src/daemon/skills/directive.md +++ b/makima/src/daemon/skills/directive.md @@ -92,7 +92,7 @@ Options: - `--choices "opt1,opt2,opt3"` - Provide choices for the user to select from - `--context "<context>"` - Additional context to help the user understand the question - `--timeout <seconds>` - Wait timeout (default: 3600 = 1 hour) -- `--phaseguard` - Block indefinitely until the user responds (no timeout). Recommended for critical decisions during planning. +- `--phaseguard` - Wait indefinitely until the user responds (no timeout). The CLI automatically reconnects via polling every ~5 minutes to avoid HTTP timeout limits. Recommended for critical decisions during planning. - `--multi-select` - Allow the user to select multiple choices - `--non-blocking` - Return immediately without waiting for a response - `--question-type <general|phase_confirmation|contract_complete>` - Question type @@ -108,6 +108,31 @@ Options: makima directive ask "Should we use REST or GraphQL for the new API?" --choices "REST,GraphQL" --context "The existing codebase uses REST but the frontend team prefers GraphQL" --phaseguard ``` +### Create an Order (Future Work) +```bash +makima directive create-order --title "Order title" --order-type spike +``` +Creates an order for future work that is automatically linked to the current directive. Only `spike` and `chore` order types are allowed. + +Options: +- `--title "<title>"` - (Required) Title of the order +- `--description "<description>"` - Optional description of the work +- `--priority <critical|high|medium|low|none>` - Priority level (default: medium) +- `--order-type <spike|chore>` - Type of work (default: spike). Only spike and chore are allowed. +- `--labels "label1,label2"` - Optional comma-separated labels + +**When to use:** +- When you discover work that is out of scope for the current directive step but should be tracked +- When a spike reveals follow-up tasks that need to be done later +- When you identify technical debt or maintenance work during implementation +- When a chore (e.g., dependency update, config change) is needed but not part of the current goal + +**Example:** +```bash +makima directive create-order --title "Investigate flaky test in auth module" --order-type spike --priority high --description "The auth module tests intermittently fail on CI. Needs investigation." --labels "testing,auth" +makima directive create-order --title "Update deprecated serde API usage" --order-type chore --priority low --labels "tech-debt" +``` + ## Memory Commands Directives have an optional key-value memory system that persists across steps and planning cycles. Use memory to share context, decisions, and learned information between steps — so downstream tasks don't need to re-discover what earlier steps already figured out. diff --git a/makima/src/orchestration/directive.rs b/makima/src/orchestration/directive.rs index b91781c..98690bb 100644 --- a/makima/src/orchestration/directive.rs +++ b/makima/src/orchestration/directive.rs @@ -1371,8 +1371,9 @@ If you need clarification from the user before finalizing the plan, you can ask makima directive ask "Confirm this approach?" --context "Additional context here" --phaseguard Use --phaseguard for questions that block progress (the question will wait indefinitely for a response). +The CLI automatically reconnects via polling every ~5 minutes to avoid HTTP timeout limits. Without --phaseguard, questions timeout based on the directive's reconcile mode: -- Reconcile ON: questions block indefinitely until answered +- Reconcile ON: questions wait indefinitely (with automatic reconnecting polls every ~5 min) - Reconcile OFF: questions timeout after 30 seconds with no response When to ask: @@ -1385,6 +1386,23 @@ Do NOT ask questions for: - Implementation details you can determine from the codebase - Standard engineering decisions with clear best practices - Trivial choices that do not significantly affect the outcome + +CREATING ORDERS FOR FUTURE WORK: +If you discover work that is out of scope for the current plan but should be tracked, create an order: + makima directive create-order --title "Order title" --order-type spike + makima directive create-order --title "Fix flaky test" --order-type chore --priority high --description "Details..." + +Only spike and chore types are allowed. The order is automatically linked to this directive. + +When to create orders: +- You discover follow-up work that is outside the current goal +- A spike reveals additional tasks that need future attention +- You identify technical debt or maintenance chores during planning +- Something needs investigation but is not blocking the current plan + +Do NOT create orders for: +- Work that should be a step in the current plan +- Tasks that are part of the current goal "#, title = directive.title, goal = directive.goal, diff --git a/makima/src/server/handlers/mesh_supervisor.rs b/makima/src/server/handlers/mesh_supervisor.rs index 0ea1a57..8c36500 100644 --- a/makima/src/server/handlers/mesh_supervisor.rs +++ b/makima/src/server/handlers/mesh_supervisor.rs @@ -14,7 +14,7 @@ use serde::{Deserialize, Serialize}; use utoipa::ToSchema; use uuid::Uuid; -use crate::db::models::{CreateTaskRequest, PendingQuestion, Task, TaskSummary, UpdateTaskRequest}; +use crate::db::models::{CreateOrderRequest, CreateTaskRequest, PendingQuestion, Task, TaskSummary, UpdateTaskRequest}; use crate::db::repository; use sqlx::PgPool; use crate::server::auth::Authenticated; @@ -95,7 +95,7 @@ fn default_question_timeout() -> i32 { } /// Response from asking a question. -#[derive(Debug, Serialize, ToSchema)] +#[derive(Debug, Serialize, Deserialize, ToSchema)] #[serde(rename_all = "camelCase")] pub struct AskQuestionResponse { /// The question ID for tracking @@ -104,6 +104,10 @@ pub struct AskQuestionResponse { pub response: Option<String>, /// Whether the question timed out pub timed_out: bool, + /// Whether the question is still pending (server-side timeout reached but question not removed). + /// The client should poll the poll endpoint to continue waiting. + #[serde(default)] + pub still_pending: bool, } /// Request to answer a supervisor question. @@ -1803,6 +1807,7 @@ pub async fn ask_question( question_id, response: None, timed_out: false, + still_pending: false, }), ).into_response(); } @@ -1815,8 +1820,9 @@ pub async fn ask_question( // - Directive tasks without reconcile mode: 30s default timeout // - Contract tasks: use requested timeout_seconds let timeout_secs = if use_phaseguard { - // Block indefinitely until user responds - u64::MAX / 2 + // Cap at 5 minutes per HTTP request (well under Claude Code's 10-min limit). + // The CLI will automatically reconnect via the poll endpoint. + 300 } else if is_directive_context && !directive_reconcile_mode { 30 } else { @@ -1844,13 +1850,28 @@ pub async fn ask_question( question_id, response: Some(response.response), timed_out: false, + still_pending: false, }), ).into_response(); } // Check timeout if start.elapsed() >= timeout_duration { - // Remove the pending question on timeout + if use_phaseguard { + // Phaseguard/reconcile: DON'T remove the pending question. + // Return still_pending so the CLI can reconnect via the poll endpoint. + return ( + StatusCode::OK, + Json(AskQuestionResponse { + question_id, + response: None, + timed_out: false, + still_pending: true, + }), + ).into_response(); + } + + // Non-phaseguard: remove the pending question on timeout state.remove_pending_question(question_id); // Clear pending question from supervisor state on timeout (Task 3.3) @@ -1865,6 +1886,125 @@ pub async fn ask_question( question_id, response: None, timed_out: true, + still_pending: false, + }), + ).into_response(); + } + + // Wait before polling again + tokio::time::sleep(poll_interval).await; + } +} + +/// Poll for a question response by question_id. +/// +/// Used by the CLI to reconnect after a still_pending response from ask_question. +/// Blocks for up to 5 minutes polling every 500ms. Returns still_pending if timeout +/// is reached without a response, allowing the CLI to reconnect again. +#[utoipa::path( + get, + path = "/api/v1/mesh/supervisor/questions/{question_id}/poll", + params( + ("question_id" = Uuid, Path, description = "The question ID to poll for"), + ), + responses( + (status = 200, description = "Question answered or still pending", body = AskQuestionResponse), + (status = 404, description = "Question not found"), + (status = 401, description = "Unauthorized"), + (status = 403, description = "Forbidden - not a supervisor"), + ), + security( + ("tool_key" = []) + ), + tag = "Mesh Supervisor" +)] +pub async fn poll_question( + State(state): State<SharedState>, + headers: HeaderMap, + Path(question_id): Path<Uuid>, +) -> impl IntoResponse { + let (supervisor_id, owner_id) = match verify_supervisor_auth(&state, &headers, None).await { + Ok(ids) => ids, + Err(e) => return e.into_response(), + }; + + // Check if a response is already available + if let Some(response) = state.get_question_response(question_id) { + state.cleanup_question_response(question_id); + + // Clear pending question from supervisor state for contract context + let pool = state.db_pool.as_ref().unwrap(); + if let Ok(Some(task)) = repository::get_task_for_owner(pool, supervisor_id, owner_id).await { + if let Some(cid) = task.contract_id { + clear_pending_question(pool, cid, question_id).await; + } + } + + return ( + StatusCode::OK, + Json(AskQuestionResponse { + question_id, + response: Some(response.response), + timed_out: false, + still_pending: false, + }), + ).into_response(); + } + + // Check if the question exists at all (pending or response) + if !state.has_pending_question(question_id) { + return ( + StatusCode::NOT_FOUND, + Json(ApiError::new("NOT_FOUND", "Question not found or already answered")), + ).into_response(); + } + + // Block for up to 5 minutes polling every 500ms + let timeout_duration = std::time::Duration::from_secs(300); + let start = std::time::Instant::now(); + let poll_interval = std::time::Duration::from_millis(500); + + loop { + // Check if response has been submitted + if let Some(response) = state.get_question_response(question_id) { + state.cleanup_question_response(question_id); + + // Clear pending question from supervisor state for contract context + let pool = state.db_pool.as_ref().unwrap(); + if let Ok(Some(task)) = repository::get_task_for_owner(pool, supervisor_id, owner_id).await { + if let Some(cid) = task.contract_id { + clear_pending_question(pool, cid, question_id).await; + } + } + + return ( + StatusCode::OK, + Json(AskQuestionResponse { + question_id, + response: Some(response.response), + timed_out: false, + still_pending: false, + }), + ).into_response(); + } + + // Check if the question was removed (e.g., task deleted) + if !state.has_pending_question(question_id) { + return ( + StatusCode::NOT_FOUND, + Json(ApiError::new("NOT_FOUND", "Question no longer exists")), + ).into_response(); + } + + // Check timeout + if start.elapsed() >= timeout_duration { + return ( + StatusCode::OK, + Json(AskQuestionResponse { + question_id, + response: None, + timed_out: false, + still_pending: true, }), ).into_response(); } @@ -2952,3 +3092,162 @@ pub fn generate_restoration_context_message(context: &SupervisorRestorationConte message } + +// ============================================================================= +// Order Creation from Directive Tasks +// ============================================================================= + +/// Request to create an order from a directive task. +#[derive(Debug, Deserialize, ToSchema)] +#[serde(rename_all = "camelCase")] +pub struct CreateOrderForTaskRequest { + pub title: String, + #[serde(default)] + pub description: Option<String>, + #[serde(default = "default_order_priority")] + pub priority: String, + #[serde(default = "default_order_type")] + pub order_type: String, + #[serde(default = "default_order_labels")] + pub labels: serde_json::Value, + #[serde(default)] + pub repository_url: Option<String>, +} + +fn default_order_priority() -> String { + "medium".to_string() +} + +fn default_order_type() -> String { + "spike".to_string() +} + +fn default_order_labels() -> serde_json::Value { + serde_json::json!([]) +} + +/// Create an order for future work from a directive task. +/// +/// Only spike and chore order types are allowed. The order is automatically +/// linked to the directive associated with the calling task. +#[utoipa::path( + post, + path = "/api/v1/mesh/supervisor/orders", + request_body = CreateOrderForTaskRequest, + responses( + (status = 201, description = "Order created"), + (status = 400, description = "Invalid order type"), + (status = 401, description = "Unauthorized"), + (status = 403, description = "Forbidden - not a supervisor/directive task"), + (status = 500, description = "Internal server error"), + ), + tag = "Mesh Supervisor" +)] +pub async fn create_order_for_task( + State(state): State<SharedState>, + headers: HeaderMap, + Json(request): Json<CreateOrderForTaskRequest>, +) -> impl IntoResponse { + let (task_id, owner_id) = match verify_supervisor_auth(&state, &headers, None).await { + Ok(ids) => ids, + Err(e) => return e.into_response(), + }; + + let pool = state.db_pool.as_ref().unwrap(); + + // Validate order_type is spike or chore + if request.order_type != "spike" && request.order_type != "chore" { + return ( + StatusCode::BAD_REQUEST, + Json(ApiError::new( + "INVALID_ORDER_TYPE", + "Only spike and chore order types are allowed from directive tasks", + )), + ) + .into_response(); + } + + // Get the task to find its directive_id + let task = match repository::get_task(pool, task_id).await { + Ok(Some(t)) => t, + Ok(None) => { + return ( + StatusCode::NOT_FOUND, + Json(ApiError::new("NOT_FOUND", "Task not found")), + ) + .into_response(); + } + Err(e) => { + tracing::error!(error = %e, "Failed to get task"); + return ( + StatusCode::INTERNAL_SERVER_ERROR, + Json(ApiError::new("DB_ERROR", "Failed to get task")), + ) + .into_response(); + } + }; + + let directive_id = match task.directive_id { + Some(id) => id, + None => { + return ( + StatusCode::BAD_REQUEST, + Json(ApiError::new( + "NO_DIRECTIVE", + "Task is not associated with a directive", + )), + ) + .into_response(); + } + }; + + // Determine repository_url: use request value, or fall back to directive's repository_url + let repository_url = if request.repository_url.is_some() { + request.repository_url + } else { + // Look up directive for its repository_url + match repository::get_directive_for_owner(pool, owner_id, directive_id).await { + Ok(Some(d)) => d.repository_url, + _ => None, + } + }; + + // Create the order + let order_req = CreateOrderRequest { + title: request.title, + description: request.description, + priority: Some(request.priority), + status: Some("open".to_string()), + order_type: Some(request.order_type), + labels: request.labels, + directive_id, + repository_url, + }; + + match repository::create_order(pool, owner_id, order_req).await { + Ok(order) => ( + StatusCode::CREATED, + Json(serde_json::json!({ + "id": order.id, + "title": order.title, + "description": order.description, + "priority": order.priority, + "status": order.status, + "orderType": order.order_type, + "directiveId": order.directive_id, + "labels": order.labels, + "repositoryUrl": order.repository_url, + "createdAt": order.created_at, + })), + ) + .into_response(), + Err(e) => { + tracing::error!(error = %e, "Failed to create order"); + ( + StatusCode::INTERNAL_SERVER_ERROR, + Json(ApiError::new("DB_ERROR", "Failed to create order")), + ) + .into_response() + } + } +} diff --git a/makima/src/server/mod.rs b/makima/src/server/mod.rs index 1ad3a8d..e0f8e7d 100644 --- a/makima/src/server/mod.rs +++ b/makima/src/server/mod.rs @@ -129,8 +129,11 @@ pub fn make_router(state: SharedState) -> Router { .route("/mesh/supervisor/tasks/{task_id}/merge", post(mesh_supervisor::merge_task)) .route("/mesh/supervisor/tasks/{task_id}/diff", get(mesh_supervisor::get_task_diff)) .route("/mesh/supervisor/pr", post(mesh_supervisor::create_pr)) + // Supervisor order creation endpoint + .route("/mesh/supervisor/orders", post(mesh_supervisor::create_order_for_task)) // Supervisor question endpoints .route("/mesh/supervisor/questions", post(mesh_supervisor::ask_question)) + .route("/mesh/supervisor/questions/{question_id}/poll", get(mesh_supervisor::poll_question)) .route("/mesh/questions", get(mesh_supervisor::list_pending_questions)) .route("/mesh/questions/{question_id}/answer", post(mesh_supervisor::answer_question)) // Mesh WebSocket endpoints diff --git a/makima/src/server/state.rs b/makima/src/server/state.rs index 41c336e..15fec6b 100644 --- a/makima/src/server/state.rs +++ b/makima/src/server/state.rs @@ -910,6 +910,11 @@ impl AppState { self.pending_questions.get(&question_id).map(|entry| entry.value().clone()) } + /// Check if a pending question exists (either still pending or has a response ready). + pub fn has_pending_question(&self, question_id: Uuid) -> bool { + self.pending_questions.contains_key(&question_id) || self.question_responses.contains_key(&question_id) + } + /// Submit a response to a supervisor question. pub fn submit_question_response(&self, question_id: Uuid, response: String) -> bool { // Check if the question exists |