@ekkos/cli 1.0.34 → 1.0.36

package/templates/hooks/user-prompt-submit.sh

@@ -108,7 +108,7 @@ if [ -f "$EKKOS_CONFIG" ] && [ -f "$JSON_PARSE_HELPER" ]; then
 fi
 [ -z "$AUTH_TOKEN" ] && AUTH_TOKEN=$(grep -E "^SUPABASE_SECRET_KEY=" "$PROJECT_ROOT/.env.local" 2>/dev/null | cut -d'=' -f2- | tr -d '"' | tr -d "'" || echo "")
 
-MEMORY_API_URL="https://mcp.ekkos.dev"
+MEMORY_API_URL="https://api.ekkos.dev"
 
 # ═══════════════════════════════════════════════════════════════════════════
 # Session ID
@@ -327,7 +327,7 @@ const body = JSON.stringify({
     pendingSession: process.argv[4]
 });
 const req = https.request({
-    hostname: 'mcp.ekkos.dev',
+    hostname: 'api.ekkos.dev',
     path: '/proxy/session/bind',
     method: 'POST',
     headers: {'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body)}

package/templates/windsurf-hooks/before-submit-prompt.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS_ Hook: BeforeSubmitPrompt (Windsurf Cascade) - RETRIEVE + INJECT + CONTRACT
+#
+# ARCHITECTURE: Dumb Hook, Smart Backend
+# ═══════════════════════════════════════════════════════════════════════════
+# This hook runs BEFORE the prompt is sent to the AI.
+# It is THE CANONICAL retrieval path for Windsurf.
+#
+# GOLDEN LOOP ENFORCEMENT:
+# - Writes turn contract as evidence of retrieval
+# - In STRICT mode, returns continue=false to block turn
+# - Lists pattern IDs explicitly for PatternGuard validation
+# ═══════════════════════════════════════════════════════════════════════════
+
+set +e  # Don't exit on errors - be bulletproof
+
+# Get project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+STATE_DIR="$PROJECT_ROOT/.windsurf/state"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+# Load turn contract library
+if [ -f "$SCRIPT_DIR/lib/contract.sh" ]; then
+  source "$SCRIPT_DIR/lib/contract.sh" 2>/dev/null || true
+fi
+
+# Fallback functions if library didn't load
+if ! command -v write_turn_contract >/dev/null 2>&1; then
+  write_turn_contract() { return 0; }
+fi
+if ! command -v generate_query_hash >/dev/null 2>&1; then
+  generate_query_hash() { echo "$(date +%s)"; }
+fi
+if ! command -v is_strict_mode >/dev/null 2>&1; then
+  is_strict_mode() { [ "${EKKOS_STRICT:-0}" = "1" ]; }
+fi
+if ! command -v get_strict_blocker_message >/dev/null 2>&1; then
+  get_strict_blocker_message() { echo "⛔ EKKOS_STRICT: Retrieval failed - DO NOT ANSWER"; }
+fi
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract prompt text and session info
+PROMPT_TEXT=$(echo "$INPUT" | jq -r '.prompt // .text // ""' 2>/dev/null || echo "")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .conversation_id // ""' 2>/dev/null || echo "")
+MODEL_INFO=$(echo "$INPUT" | jq -r '.model // ""' 2>/dev/null || echo "")
+
+# Generate session ID if not provided
+if [ -z "$SESSION_ID" ] || [ "$SESSION_ID" = "null" ]; then
+  SESSION_ID="windsurf-$(date +%s)-$$"
+fi
+
+# Skip if empty
+if [ -z "$PROMPT_TEXT" ] || [ "$PROMPT_TEXT" = "null" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Generate query hash for contract
+QUERY_HASH=$(generate_query_hash "$PROMPT_TEXT")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Load auth token - PORTABLE: Check 3 sources in priority order
+# ═══════════════════════════════════════════════════════════════════════════
+EKKOS_CONFIG="$HOME/.ekkos/config.json"
+AUTH_TOKEN=""
+USER_ID=""
+
+# 1. First try ~/.ekkos/config.json (set by VS Code extension - most portable)
+#    Prefer hookApiKey (scoped key for hooks) over apiKey (legacy)
+if [ -f "$EKKOS_CONFIG" ]; then
+  AUTH_TOKEN=$(jq -r '.hookApiKey // .apiKey // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
+  USER_ID=$(jq -r '.userId // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
+fi
+
+# 2. Then try project .env.local (for developers)
+if [ -z "$AUTH_TOKEN" ] && [ -f "$PROJECT_ROOT/.env.local" ]; then
+  AUTH_TOKEN=$(grep -E "^SUPABASE_SECRET_KEY=" "$PROJECT_ROOT/.env.local" | cut -d'=' -f2- | tr -d '"' | tr -d "'" | tr -d '\r')
+fi
+
+# 3. Finally try environment variable
+if [ -z "$AUTH_TOKEN" ]; then
+  AUTH_TOKEN="${SUPABASE_SECRET_KEY:-}"
+fi
+
+# Track retrieval status
+RETRIEVAL_OK="false"
+RETRIEVED_PATTERN_IDS=""
+RETRIEVED_DIRECTIVE_IDS=""
+
+# Skip if no auth
+if [ -z "$AUTH_TOKEN" ]; then
+  # STRICT MODE: Block turn if no auth
+  if is_strict_mode; then
+    BLOCKER_MSG=$(get_strict_blocker_message)
+    write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+    echo "{\"continue\": false, \"user_message\": $(echo "$BLOCKER_MSG" | jq -R -s .)}"
+    exit 0
+  fi
+
+  write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+  echo '{"continue": true, "user_message": "[ekkOS] No auth token. Run ekkOS: Connect in VS Code."}'
+  exit 0
+fi
+
+# Cloud API
+MEMORY_API_URL="https://mcp.ekkos.dev"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_RETRIEVE] Search memory for patterns (all 8 queryable layers)
+# ═══════════════════════════════════════════════════════════════════════════
+JSON_PAYLOAD=$(jq -n \
+  --arg query "$PROMPT_TEXT" \
+  --arg user_id "${USER_ID:-system}" \
+  --arg session "windsurf-$SESSION_ID" \
+  '{
+    query: $query,
+    user_id: $user_id,
+    session_id: $session,
+    max_per_layer: 5,
+    include_layers: ["working", "episodic", "semantic", "patterns", "procedural", "collective", "codebase", "directives"],
+    metadata: { source: "windsurf-cascade-hook" }
+  }' 2>/dev/null || echo '{}')
+
+API_RESPONSE=$(curl -s -X POST "$MEMORY_API_URL/api/v1/context/retrieve" \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD" \
+  --connect-timeout 3 \
+  --max-time 5 2>/dev/null || echo '{"error":"timeout"}')
+
+# Check if retrieval succeeded
+if echo "$API_RESPONSE" | jq -e '.layers' >/dev/null 2>&1; then
+  RETRIEVAL_OK="true"
+else
+  # STRICT MODE: Block turn if retrieval failed
+  if is_strict_mode; then
+    BLOCKER_MSG=$(get_strict_blocker_message)
+    write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+    echo "{\"continue\": false, \"user_message\": $(echo "$BLOCKER_MSG" | jq -R -s .)}"
+    exit 0
+  fi
+
+  API_RESPONSE='{"error":"timeout","formatted_context":"","layers":{"patterns":[],"directives":[]}}'
+fi
+
+# Extract counts
+PATTERN_COUNT=$(echo "$API_RESPONSE" | jq '.layers.patterns // [] | length' 2>/dev/null || echo "0")
+DIRECTIVE_COUNT=$(echo "$API_RESPONSE" | jq '.layers.directives // [] | length' 2>/dev/null || echo "0")
+TOTAL_COUNT=$((PATTERN_COUNT + DIRECTIVE_COUNT))
+
+# Extract pattern and directive IDs for turn contract
+RETRIEVED_PATTERN_IDS=$(echo "$API_RESPONSE" | jq -r '.layers.patterns // [] | map(.pattern_id // .id) | join(",")' 2>/dev/null || echo "")
+RETRIEVED_DIRECTIVE_IDS=$(echo "$API_RESPONSE" | jq -r '.layers.directives // [] | map(.directive_id // .id) | join(",")' 2>/dev/null || echo "")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_CONTRACT] Write turn contract as evidence of retrieval
+# ═══════════════════════════════════════════════════════════════════════════
+write_turn_contract "$SESSION_ID" "$RETRIEVAL_OK" "windsurf" "$RETRIEVED_PATTERN_IDS" "$RETRIEVED_DIRECTIVE_IDS" "$QUERY_HASH" "$PROJECT_ROOT"
+
+# Save session ID to state file
+echo "$SESSION_ID" > "$STATE_DIR/current_session_id.txt" 2>/dev/null || true
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_INJECT] Build user message with patterns
+# ═══════════════════════════════════════════════════════════════════════════
+if [ "$PATTERN_COUNT" -gt 0 ]; then
+  # Get formatted context
+  FORMATTED=$(echo "$API_RESPONSE" | jq -r '.formatted_context // ""' 2>/dev/null)
+
+  # Get pattern IDs for PatternGuard
+  PATTERN_ID_LIST=$(echo "$API_RESPONSE" | jq -r '.layers.patterns[:5][] | .pattern_id // .id' 2>/dev/null || echo "")
+
+  if [ -n "$FORMATTED" ] && [ "$FORMATTED" != "null" ]; then
+    MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™ Memory Substrate
+✓ $PATTERN_COUNT patterns loaded from memory
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+$FORMATTED
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  PATTERNGUARD REQUIRED
+
+You MUST acknowledge ALL $PATTERN_COUNT pattern(s) above.
+
+Pattern IDs to acknowledge:
+$PATTERN_ID_LIST
+
+For patterns you USE:
+[ekkOS_SELECT]
+- id: <pattern-uuid>
+  reason: <why using>
+  confidence: <0.0-1.0>
+[/ekkOS_SELECT]
+
+For patterns you DO NOT use:
+[ekkOS_SKIP]
+- id: <pattern-uuid>
+  reason: <why not relevant>
+[/ekkOS_SKIP]
+
+Coverage MUST be 100% (all IDs acknowledged).
+
+RESPONSE FORMAT: End with:
+🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  else
+    # Fallback: minimal injection
+    MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™: $PATTERN_COUNT patterns found
+
+Pattern IDs to acknowledge with [ekkOS_SELECT] or [ekkOS_SKIP]:
+$PATTERN_ID_LIST
+
+End response with: 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  fi
+
+  # Save patterns for capture
+  echo "$API_RESPONSE" | jq '.layers.patterns // []' > "$STATE_DIR/patterns-${SESSION_ID}.json" 2>/dev/null || true
+
+  echo "{\"continue\": true, \"user_message\": $(echo "$MESSAGE" | jq -R -s .)}" | jq -c .
+else
+  # No patterns - still write contract and remind about footer
+  MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™: No patterns found (new territory)
+
+End response with: 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  echo "{\"continue\": true, \"user_message\": $(echo "$MESSAGE" | jq -R -s .)}" | jq -c .
+fi
+
+exit 0

package/templates/windsurf-skills/ekkos-memory/SKILL.md

@@ -0,0 +1,219 @@
+---
+title: ekkOS Memory System
+description: AI-native cognitive memory with 31 MCP tools for persistent learning and context continuity
+trigger: always_on
+author: ekkOS Technologies
+tags: [memory, patterns, learning, context]
+---
+
+# ekkOS Memory System Skill
+
+This skill enables Cascade to leverage the full ekkOS 11-layer cognitive memory system for persistent learning, pattern recognition, and context continuity across sessions.
+
+## When to Use This Skill
+
+**ALWAYS USE** for:
+- Technical questions (before answering, search memory)
+- Bug fixes (forge patterns after solving)
+- Architecture decisions (check for existing patterns)
+- Code reviews (retrieve relevant patterns)
+- Refactoring (find proven approaches)
+
+## Core Workflow
+
+### 1. Search Before Answering (MANDATORY)
+
+```
+Before answering ANY technical question:
+
+1. Call ekkOS_Search with the query
+2. Review retrieved patterns
+3. Acknowledge ALL patterns with [ekkOS_SELECT] or [ekkOS_SKIP]
+4. THEN provide your answer
+```
+
+### 2. PatternGuard Acknowledgment
+
+For every pattern retrieved, you MUST acknowledge it:
+
+```
+[ekkOS_SELECT]
+- id: <pattern-uuid>
+  reason: Using this because...
+  confidence: 0.95
+[/ekkOS_SELECT]
+
+[ekkOS_SKIP]
+- id: <pattern-uuid>
+  reason: Not relevant because...
+[/ekkOS_SKIP]
+```
+
+**Coverage must be 100%** - every pattern ID must be acknowledged.
+
+### 3. Forge What You Learn
+
+After fixing bugs, solving problems, or discovering gotchas:
+
+```
+Call ekkOS_Forge with:
+- Problem: What was broken
+- Solution: How you fixed it
+- Tags: [language, framework, error-type]
+```
+
+## MCP Tools Reference
+
+### Core Memory (8 tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `ekkOS_Search` | Search all 11 memory layers | **Before EVERY technical answer** |
+| `ekkOS_Context` | Get relevant task context | When starting multi-step tasks |
+| `ekkOS_Capture` | Capture memory events | Log significant actions |
+| `ekkOS_Forge` | Create patterns from solutions | After fixing bugs/discoveries |
+| `ekkOS_Directive` | Create MUST/NEVER/PREFER/AVOID rules | When user states preferences |
+| `ekkOS_Outcome` | Track success/failure | After applying patterns |
+| `ekkOS_Detect` | Auto-detect pattern usage | In responses |
+| `ekkOS_Recall` | Recall past conversations | When user asks "what did we" |
+
+### Schema Awareness (2 tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `ekkOS_IndexSchema` | Index database schemas | With Supabase/Prisma projects |
+| `ekkOS_GetSchema` | Get specific table schema | When writing queries |
+
+### Plan Management (9 tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `ekkOS_Plan` | Create structured plans | Multi-step features |
+| `ekkOS_Generate` | AI-generate plans | Complex tasks |
+| `ekkOS_PlanStatus` | Update plan status | Marking steps complete |
+| `ekkOS_PlanStep` | Mark step done | Step completion |
+| `ekkOS_SaveTemplate` | Save as template | Reusable workflows |
+| `ekkOS_Templates` | List templates | Finding existing plans |
+| `ekkOS_FromTemplate` | Create from template | Starting from template |
+
+### Portability & Secrets (8 tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `ekkOS_Export` | Export as backup | Before major changes |
+| `ekkOS_Import` | Import from backup | Restoring context |
+| `ekkOS_StoreSecret` | Encrypt credentials | Storing API keys |
+| `ekkOS_GetSecret` | Retrieve secrets | Using stored credentials |
+| `ekkOS_ListSecrets` | List secret metadata | Checking what's stored |
+| `ekkOS_RotateSecret` | Rotate secret values | Key rotation |
+
+### System Health (4 tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `ekkOS_Stats` | Get layer statistics | Health checks |
+| `ekkOS_Summary` | Get activity summary | Progress updates |
+| `ekkOS_Conflict` | Check for conflicts | Before dangerous ops |
+| `ekkOS_Reflect` | Analyze for improvements | Post-task review |
+
+## 11-Layer Architecture
+
+| Layer | Purpose | Example Content |
+|-------|---------|-----------------|
+| 1 | Working | Current session context |
+| 2 | Episodic | Past conversation turns |
+| 3 | Semantic | Embeddings/vectors |
+| 4 | Patterns | Proven solutions |
+| 5 | Procedural | Step-by-step guides |
+| 6 | Collective | Community patterns |
+| 7 | Meta | Pattern effectiveness |
+| 8 | Codebase | Project code context |
+| 9 | Directives | User rules (MUST/NEVER) |
+| 10 | Conflict | Auto-resolution rules |
+| 11 | Secrets | Encrypted credentials |
+
+## Forge Triggers
+
+**Always forge when you:**
+- Fix a bug (create anti-pattern from the bug)
+- Find a better approach (update existing pattern)
+- Discover a gotcha (create warning pattern)
+- Get corrected by user (learn from correction)
+- Solve auth/config issues (create setup pattern)
+- Make architecture decisions (document rationale)
+- Debug non-trivially (capture the journey)
+
+## Response Format
+
+End EVERY response with:
+
+```
+🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
+```
+
+## Examples
+
+### Example 1: Technical Question
+
+User: "How do I fix CORS in Next.js?"
+
+Your workflow:
+1. Call `ekkOS_Search` with query: "Next.js CORS fix"
+2. Review retrieved patterns
+3. Acknowledge all patterns with SELECT/SKIP
+4. Provide answer based on patterns + your knowledge
+5. End with footer
+
+### Example 2: Bug Fix
+
+User: "The build is failing with this error..."
+
+Your workflow:
+1. Call `ekkOS_Search` with error message
+2. Apply relevant patterns
+3. Acknowledge with SELECT
+4. Fix the bug
+5. Call `ekkOS_Forge` with the solution
+6. Call `ekkOS_Outcome` to track success
+
+### Example 3: User Preference
+
+User: "I always want TypeScript strict mode"
+
+Your workflow:
+1. Call `ekkOS_Directive`:
+   - type: PREFER
+   - rule: "Use TypeScript strict mode"
+   - scope: project
+2. Acknowledge in future responses
+
+## Best Practices
+
+1. **Search first** - Never answer without searching
+2. **Acknowledge all** - 100% PatternGuard coverage required
+3. **Forge immediately** - Don't wait to capture learnings
+4. **Track outcomes** - Success/failure feedback improves patterns
+5. **Use directives** - Convert user preferences to rules
+6. **Export regularly** - Backup before major changes
+7. **End with footer** - Every response needs the ekkOS footer
+
+## Troubleshooting
+
+**"No patterns found"**
+→ You're in new territory. Forge what you discover.
+
+**"Pattern retrieval failed"**
+→ Check auth: `~/.ekkos/config.json` should have hookApiKey
+
+**"How do I continue from last session?"**
+→ Ask: "recall our last conversation" or "where were we"
+
+## Resources
+
+- Website: https://ekkos.dev
+- Docs: https://docs.ekkos.dev
+- Support: support@ekkos.dev
+
+---
+
+🧠 **ekkOS_™** · Built for infinite context

package/README.md

@@ -1,57 +0,0 @@
-# @ekkos/cli
-
-Persistent cognitive memory for AI coding assistants. ekkOS gives Claude Code, Cursor, and Windsurf long-term memory — patterns, decisions, and operational intelligence that compound across every interaction.
-
-## Quick Start
-
-```bash
-# Install globally
-npm install -g @ekkos/cli
-
-# Authenticate and configure your IDE
-ekkos init
-
-# Launch Claude Code with memory
-ekkos run
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ekkos init` | Authenticate and configure your IDE (Claude Code, Cursor, Windsurf) |
-| `ekkos run` | Launch Claude Code with ekkOS memory connected |
-| `ekkos run --dashboard` | Launch with live metrics dashboard (tmux split) |
-| `ekkos status` | Check connection and memory health |
-| `ekkos dashboard` | Open the live session dashboard |
-| `ekkos export` | Export your patterns and memory as JSON |
-| `ekkos --help` | Show all commands |
-
-## What It Does
-
-- **Remembers what works** — Patterns from successful solutions are recalled automatically
-- **Learns from mistakes** — Anti-patterns prevent repeating the same errors
-- **Crosses sessions** — Knowledge persists across conversations, projects, and tools
-- **Gets smarter over time** — Success rates compound as patterns are verified
-
-## How It Works
-
-ekkOS installs hooks into your AI coding assistant that:
-
-1. **Before each prompt** — Searches 11 memory layers for relevant patterns
-2. **After each response** — Captures new solutions as reusable patterns
-3. **Between sessions** — Preserves context through eviction and rehydration
-
-## Requirements
-
-- Node.js >= 18
-- An ekkOS account ([platform.ekkos.dev](https://platform.ekkos.dev/signup))
-- One of: Claude Code, Cursor, Windsurf, or VS Code
-
-## Documentation
-
-[docs.ekkos.dev](https://docs.ekkos.dev)
-
-## License
-
-Proprietary — see [ekkos.dev/terms](https://ekkos.dev/terms)