@formthefog/stratus 2026.2.17

package/install.sh

@@ -0,0 +1,215 @@
+#!/bin/bash
+set -e
+
+# Stratus OpenClaw Plugin Installer
+#
+# Note: You can also use /stratus setup in any OpenClaw chat!
+# This script is an alternative for users who prefer manual setup.
+#
+# Makes installation feel like butter 🧈
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  🌊 Stratus X1 OpenClaw Plugin Installer"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Detect OS
+OS=$(uname -s)
+SHELL_CONFIG=""
+
+if [[ "$OS" == "Darwin" ]]; then
+    # macOS
+    if [[ -n "$ZSH_VERSION" ]] || [[ "$SHELL" == *"zsh"* ]]; then
+        SHELL_CONFIG="$HOME/.zshrc"
+    else
+        SHELL_CONFIG="$HOME/.bash_profile"
+    fi
+elif [[ "$OS" == "Linux" ]]; then
+    # Linux
+    if [[ -n "$ZSH_VERSION" ]] || [[ "$SHELL" == *"zsh"* ]]; then
+        SHELL_CONFIG="$HOME/.zshrc"
+    else
+        SHELL_CONFIG="$HOME/.bashrc"
+    fi
+fi
+
+# Check for existing API key
+EXISTING_KEY="${STRATUS_API_KEY:-}"
+
+if [[ -z "$EXISTING_KEY" ]]; then
+    echo "📝 Enter your Stratus API key:"
+    echo "   (Get one at: https://stratus.run)"
+    echo ""
+    read -p "API Key: " API_KEY
+
+    if [[ -z "$API_KEY" ]]; then
+        echo "❌ API key is required"
+        exit 1
+    fi
+
+    if [[ ! "$API_KEY" =~ ^stratus_sk_ ]]; then
+        echo "❌ Invalid API key format (must start with 'stratus_sk_')"
+        exit 1
+    fi
+else
+    echo "✓ Using existing STRATUS_API_KEY from environment"
+    API_KEY="$EXISTING_KEY"
+fi
+
+echo ""
+echo "🔧 Configuring OpenClaw..."
+echo ""
+
+# Paths
+OPENCLAW_CONFIG="$HOME/.openclaw/openclaw.json"
+AUTH_PROFILES="$HOME/.openclaw/agents/main/agent/auth-profiles.json"
+LAUNCHD_PLIST="$HOME/Library/LaunchAgents/ai.openclaw.gateway.plist"
+
+# Backup configs
+echo "  📦 Creating backups..."
+if [[ -f "$OPENCLAW_CONFIG" ]]; then
+    cp "$OPENCLAW_CONFIG" "${OPENCLAW_CONFIG}.backup-$(date +%Y%m%d-%H%M%S)"
+fi
+if [[ -f "$AUTH_PROFILES" ]]; then
+    cp "$AUTH_PROFILES" "${AUTH_PROFILES}.backup-$(date +%Y%m%d-%H%M%S)"
+fi
+
+# Update OpenClaw config using jq
+echo "  🔧 Updating OpenClaw configuration..."
+
+# Add models.providers.stratus if not present
+if ! jq -e '.models.providers.stratus' "$OPENCLAW_CONFIG" > /dev/null 2>&1; then
+    jq --arg baseUrl "https://dev.api.stratus.run/v1" \
+       '.models.providers.stratus = {
+          baseUrl: $baseUrl,
+          api: "openai-completions",
+          models: [
+            {
+              id: "stratus-x1ac-base-claude-sonnet-4-5",
+              name: "Stratus X1AC Base (Claude 4.5 Sonnet)",
+              reasoning: true,
+              input: ["text", "image"],
+              cost: {input: 0, output: 0, cacheRead: 0, cacheWrite: 0},
+              contextWindow: 200000,
+              maxTokens: 8192
+            }
+          ]
+        }' "$OPENCLAW_CONFIG" > "${OPENCLAW_CONFIG}.tmp" && mv "${OPENCLAW_CONFIG}.tmp" "$OPENCLAW_CONFIG"
+    echo "    ✓ Added Stratus provider configuration"
+else
+    echo "    ✓ Stratus provider already configured"
+fi
+
+# Add model alias to agents.defaults.models if not present
+if ! jq -e '.agents.defaults.models["stratus/stratus-x1ac-base-claude-sonnet-4-5"]' "$OPENCLAW_CONFIG" > /dev/null 2>&1; then
+    jq '.agents.defaults.models["stratus/stratus-x1ac-base-claude-sonnet-4-5"] = {
+          alias: "stratus",
+          params: {}
+        }' "$OPENCLAW_CONFIG" > "${OPENCLAW_CONFIG}.tmp" && mv "${OPENCLAW_CONFIG}.tmp" "$OPENCLAW_CONFIG"
+    echo "    ✓ Added model alias 'stratus'"
+else
+    echo "    ✓ Model alias already configured"
+fi
+
+# Update auth profiles
+echo "  🔑 Configuring authentication..."
+mkdir -p "$(dirname "$AUTH_PROFILES")"
+
+if [[ ! -f "$AUTH_PROFILES" ]]; then
+    # Create new auth profiles file
+    cat > "$AUTH_PROFILES" << EOF
+{
+  "version": 1,
+  "profiles": {
+    "stratus:default": {
+      "type": "api_key",
+      "provider": "stratus",
+      "key": "$API_KEY"
+    }
+  },
+  "lastGood": {
+    "stratus": "stratus:default"
+  },
+  "usageStats": {}
+}
+EOF
+    echo "    ✓ Created auth profile"
+else
+    # Update existing auth profiles
+    jq --arg key "$API_KEY" \
+       '.profiles["stratus:default"] = {
+          type: "api_key",
+          provider: "stratus",
+          key: $key
+        } |
+        .lastGood.stratus = "stratus:default"' "$AUTH_PROFILES" > "${AUTH_PROFILES}.tmp" && mv "${AUTH_PROFILES}.tmp" "$AUTH_PROFILES"
+    echo "    ✓ Updated auth profile"
+fi
+
+# Update shell config (optional)
+if [[ -n "$SHELL_CONFIG" ]] && [[ "$EXISTING_KEY" != "$API_KEY" ]]; then
+    echo ""
+    read -p "  Add STRATUS_API_KEY to $SHELL_CONFIG? (y/N): " ADD_TO_SHELL
+    if [[ "$ADD_TO_SHELL" =~ ^[Yy]$ ]]; then
+        if ! grep -q "STRATUS_API_KEY" "$SHELL_CONFIG"; then
+            cat >> "$SHELL_CONFIG" << EOF
+
+# Stratus X1 configuration for OpenClaw
+export STRATUS_API_KEY=$API_KEY
+export STRATUS_BASE_URL=https://dev.api.stratus.run/v1
+EOF
+            echo "    ✓ Added to $SHELL_CONFIG"
+            echo "    💡 Run: source $SHELL_CONFIG"
+        else
+            echo "    ⚠️  Already present in $SHELL_CONFIG"
+        fi
+    fi
+fi
+
+# Update LaunchAgent plist (macOS only)
+if [[ "$OS" == "Darwin" ]] && [[ -f "$LAUNCHD_PLIST" ]]; then
+    echo ""
+    read -p "  Add STRATUS_API_KEY to LaunchAgent? (y/N): " ADD_TO_PLIST
+    if [[ "$ADD_TO_PLIST" =~ ^[Yy]$ ]]; then
+        if ! grep -q "STRATUS_API_KEY" "$LAUNCHD_PLIST"; then
+            # Backup plist
+            cp "$LAUNCHD_PLIST" "${LAUNCHD_PLIST}.backup-$(date +%Y%m%d-%H%M%S)"
+
+            # Add environment variables to plist
+            /usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:STRATUS_API_KEY string $API_KEY" "$LAUNCHD_PLIST" 2>/dev/null || \
+            /usr/libexec/PlistBuddy -c "Set :EnvironmentVariables:STRATUS_API_KEY $API_KEY" "$LAUNCHD_PLIST"
+
+            /usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:STRATUS_BASE_URL string https://dev.api.stratus.run/v1" "$LAUNCHD_PLIST" 2>/dev/null || \
+            /usr/libexec/PlistBuddy -c "Set :EnvironmentVariables:STRATUS_BASE_URL https://dev.api.stratus.run/v1" "$LAUNCHD_PLIST"
+
+            echo "    ✓ Updated LaunchAgent plist"
+            echo "    💡 Restart gateway: openclaw gateway stop && openclaw gateway install"
+        else
+            echo "    ⚠️  Already present in LaunchAgent"
+        fi
+    fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  ✅ Installation Complete!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "🎯 Next steps:"
+echo ""
+echo "  1. Restart OpenClaw gateway:"
+echo "     openclaw gateway stop && openclaw gateway install"
+echo ""
+echo "  2. Verify installation:"
+echo "     openclaw models list | grep stratus"
+echo "     openclaw plugins info stratus"
+echo ""
+echo "  3. Test the Stratus model:"
+echo "     openclaw agent 'Hello from Stratus!' --model stratus"
+echo ""
+echo "📚 Available tools:"
+echo "  • stratus_embeddings - Generate semantic embeddings"
+echo "  • stratus_rollout - Multi-step task planning"
+echo ""
+echo "🌊 Enjoy Stratus X1!"
+echo ""

package/openclaw.plugin.json

@@ -0,0 +1,62 @@
+{
+  "id": "stratus",
+  "providers": ["stratus"],
+  "tools": ["stratus_embeddings", "stratus_rollout"],
+  "skills": ["./skills/stratus-info"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable Stratus plugin"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Stratus API key (or use STRATUS_API_KEY env var)"
+      },
+      "baseUrl": {
+        "type": "string",
+        "default": "https://dev.api.stratus.run",
+        "description": "Stratus API base URL"
+      },
+      "provider": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true
+          },
+          "defaultModel": {
+            "type": "string",
+            "default": "stratus-x1ac-base-claude-sonnet-4-5"
+          }
+        }
+      },
+      "tools": {
+        "type": "object",
+        "properties": {
+          "embeddings": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true
+              }
+            }
+          },
+          "rollout": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@formthefog/stratus",
+  "version": "2026.2.17",
+  "description": "Stratus API integration for OpenClaw - action-conditioned JEPA for autonomous agent planning",
+  "keywords": [
+    "agent",
+    "embeddings",
+    "jepa",
+    "openclaw",
+    "planning",
+    "stratus",
+    "world-model"
+  ],
+  "license": "MIT",
+  "author": "OpenClaw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formthefog/openclaw-stratus-x1-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/formthefog/openclaw-stratus-x1-plugin/issues"
+  },
+  "homepage": "https://stratus.run",
+  "type": "module",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48"
+  },
+  "scripts": {},
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/skills/stratus-info/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: stratus-info
+description: Knowledge base about Stratus X1-AC world model system
+version: 1.0.0
+author: Stratus Team
+---
+
+# Stratus X1-AC Knowledge Base
+
+## What Stratus Actually Is
+
+**Stratus is NOT just a language model with extended reasoning.**
+
+It's a **three-layer system** combining world modeling, collective intelligence, and blockchain infrastructure:
+
+---
+
+## Layer 1: Core AI (X1 & X1-AC) — The World Model
+
+This is a **hybrid architecture** with two capabilities:
+
+### 1. World Model (Predictor): "What happens if I do X?"
+- Predicts future states given current state + action
+- Uses **JEPA** (Joint-Embedding Predictive Architecture)
+- Predicts compressed representations, not raw outputs
+- Enables planning by simulating action sequences before executing
+
+### 2. Policy Head (Action Selector): "What action achieves this goal?"
+- Predicts the best action given current state + goal state
+- Fast decision-making for known patterns
+- Provides confidence scores (low confidence → escalate to LLM)
+
+**Key Innovation:**
+Instead of just guessing the next action, Stratus can **simulate the outcome of multiple actions** and pick the one most likely to achieve the goal.
+
+Think: playing chess, but for browser automation, coding, research, etc.
+
+---
+
+## Layer 2: Collective Intelligence Network
+
+Agents learn from each other in real-time:
+
+- When one agent discovers an effective approach, that knowledge flows to all agents
+- **Continuous learning**: successful patterns get canonicalized and fine-tuned into the model
+- **Domain-specific fine-tunes** (e-commerce, dev tools, research, etc.) share learnings back to the base model
+
+It's like a hive mind for AI agents — practical distributed learning at scale.
+
+---
+
+## Layer 3: Blockchain Infrastructure (L2 on Ethereum)
+
+Handles attribution, rewards, and the economic ecosystem:
+
+- Tracks who contributed what to model improvements
+- Distributes rewards to agents/operators/data providers based on contribution quality
+- Creates a marketplace for agent services, task requests, and training data
+- Uses an Ethereum L2 for fast, cheap transactions with mainnet security
+
+**Web3 infrastructure for incentivizing better AI.**
+
+---
+
+## What Makes Stratus Different
+
+### Traditional Agents (Reactive)
+```
+see → think → act → see again
+```
+❌ If something unexpected happens, they get confused
+
+### Stratus Agents (Predictive)
+```
+see → simulate outcomes → pick best action → act
+```
+✅ If something unexpected happens, they already anticipated it (or they replan)
+
+---
+
+## Available Models
+
+Stratus provides **75 models** in the format:
+
+```
+stratus-x1ac-{size}-{llm}
+```
+
+**Sizes:** `small`, `base`, `large`, `xl`, `huge`
+
+**Recommended LLMs:**
+- `claude-sonnet-4-5` - Claude 4.5 Sonnet (recommended)
+- `gpt-4o` - GPT-4 Optimized
+- `claude-haiku-4-5` - Fast, cost-effective
+
+**Example:**
+```bash
+openclaw agent "Plan a multi-step research task" \
+  --model stratus/stratus-x1ac-base-claude-sonnet-4-5
+```
+
+---
+
+## Available Tools
+
+### `stratus_embeddings`
+Generate 768-dimensional semantic state embeddings.
+
+**Use cases:**
+- Semantic search over states
+- State similarity comparison
+- Memory indexing
+- Context clustering
+
+**Example:**
+```typescript
+{
+  "tool": "stratus_embeddings",
+  "input": ["initializing", "loading", "ready", "processing", "error"]
+}
+```
+
+### `stratus_rollout`
+Multi-step action sequence planning.
+
+**Use cases:**
+- Task decomposition
+- Action planning
+- Goal-oriented reasoning
+- Multi-step workflows
+
+**Example:**
+```typescript
+{
+  "tool": "stratus_rollout",
+  "goal": "book a hotel room in Paris",
+  "max_steps": 10
+}
+```
+
+---
+
+## API Integration
+
+Stratus is **OpenAI-compatible**, meaning it's a drop-in replacement:
+
+```javascript
+// Before
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [...]
+});
+
+// After - just change endpoint and model
+const response = await openai.chat.completions.create({
+  model: "stratus-x1ac-base-gpt-4o",
+  messages: [...]
+}, {
+  baseURL: "https://dev.api.stratus.run/v1"
+});
+```
+
+Stratus handles planning, then routes execution to the specified LLM (GPT-4o, Claude, etc.).
+
+---
+
+## Common Misconceptions
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| "Stratus is just Claude with extended reasoning" | Stratus is a world model that predicts action consequences + collective learning network |
+| "It's a language model" | It's a hybrid architecture (world model + policy head) that routes to LLMs for execution |
+| "It's an LLM wrapper" | It's a JEPA-based predictive system with its own training and inference pipeline |
+
+---
+
+## Technical Reference
+
+For full technical details, see:
+- **Technical Overview:** https://stratus.run/docs/technical-overview
+- **API Documentation:** https://stratus.run/docs/api
+- **GitHub:** https://github.com/formthefog/openclaw-stratus-x1-plugin
+
+---
+
+## Quick Start
+
+1. **Install plugin:**
+   ```bash
+   openclaw plugins install @hathbanger/stratus
+   ```
+
+2. **Set API key:**
+   ```bash
+   export STRATUS_API_KEY=stratus_sk_your_key_here
+   ```
+
+3. **Run setup:**
+   ```bash
+   /stratus setup
+   ```
+
+4. **Test it:**
+   ```bash
+   openclaw agent "Hello Stratus!" --model stratus
+   ```
+
+---
+
+## When to Use Stratus
+
+**Best for:**
+- Multi-step planning tasks
+- Browser automation
+- Research workflows
+- Complex decision-making with uncertain outcomes
+- Tasks requiring "what-if" simulation
+
+**Overkill for:**
+- Simple Q&A
+- Single-shot text generation
+- Tasks without clear action sequences
+
+---
+
+**Remember:** Stratus isn't just "better reasoning" — it's **predictive planning** that fundamentally changes how agents approach tasks.
+
+🌊 Built by the Stratus team | Learn more: https://stratus.run

package/src/client.ts

@@ -0,0 +1,98 @@
+import type {
+  StratusEmbeddingsRequest,
+  StratusEmbeddingsResponse,
+  StratusPluginConfig,
+  StratusRolloutRequest,
+  StratusRolloutResponse,
+} from "./types.js";
+
+/**
+ * SECURITY MANIFEST
+ *
+ * Environment Variables Accessed:
+ * - STRATUS_API_KEY: User's Stratus API key (optional, can use config instead)
+ *
+ * Network Endpoints:
+ * - https://dev.api.stratus.run/v1/embeddings (POST)
+ * - https://dev.api.stratus.run/v1/rollout (POST)
+ *
+ * Data Transmitted:
+ * - Authorization header: Bearer token (Stratus API key)
+ * - Request body: User-provided text, goals, and parameters
+ *
+ * Data Retention:
+ * - All data sent to Stratus API per their privacy policy: https://stratus.run/privacy
+ * - No local storage of credentials beyond process memory
+ *
+ * Security:
+ * - API key validated (must start with 'stratus_sk_')
+ * - HTTPS-only connections
+ * - Keys never logged or persisted to disk by this plugin
+ */
+
+export interface StratusClientConfig {
+  apiKey: string;
+  baseUrl: string;
+}
+
+export class StratusClient {
+  constructor(private config: StratusClientConfig) {}
+
+  private async request<T>(endpoint: string, body: unknown): Promise<T> {
+    const url = `${this.config.baseUrl}${endpoint}`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Stratus API error (${response.status}): ${errorText || response.statusText}`,
+      );
+    }
+
+    return response.json();
+  }
+
+  async embeddings(params: StratusEmbeddingsRequest): Promise<StratusEmbeddingsResponse> {
+    return this.request<StratusEmbeddingsResponse>("/v1/embeddings", {
+      model: params.model || "stratus-x1ac-base",
+      input: params.input,
+      encoding_format: params.encoding_format || "float",
+    });
+  }
+
+  async rollout(params: StratusRolloutRequest): Promise<StratusRolloutResponse> {
+    return this.request<StratusRolloutResponse>("/v1/rollout", {
+      goal: params.goal,
+      initial_state: params.initial_state,
+      max_steps: params.max_steps || 10,
+      return_intermediate: params.return_intermediate ?? true,
+    });
+  }
+}
+
+export function createStratusClient(config: StratusPluginConfig | undefined): StratusClient {
+  const apiKey = config?.apiKey || process.env.STRATUS_API_KEY;
+  const baseUrl = config?.baseUrl || "https://dev.api.stratus.run";
+
+  if (!apiKey) {
+    throw new Error(
+      "Stratus API key not configured. Set STRATUS_API_KEY env var or plugins.stratus.apiKey in config.",
+    );
+  }
+
+  if (!apiKey.startsWith("stratus_sk_")) {
+    throw new Error(
+      `Invalid Stratus API key format. Expected key starting with 'stratus_sk_', got '${apiKey.substring(0, 10)}...'`,
+    );
+  }
+
+  return new StratusClient({ apiKey, baseUrl });
+}