@formthefog/stratus 2026.2.20 → 2026.3.19

package/skills/stratus-info/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: stratus-info
 description: Knowledge base about Stratus X1-AC world model system
-version: 1.0.0
+version: 2.0.0
 author: Stratus Team
 ---
 
@@ -25,10 +25,12 @@ This is a **hybrid architecture** with two capabilities:
 - Predicts compressed representations, not raw outputs
 - Enables planning by simulating action sequences before executing
 
-### 2. Policy Head (Action Selector): "What action achieves this goal?"
+### 2. Policy Head v3 (Action Selector): "What action achieves this goal?"
+- 94.41% masked accuracy — brain-guided action sequencing
 - Predicts the best action given current state + goal state
+- Returns `brain_confidence` and `brain_goal_proximity` scores
 - Fast decision-making for known patterns
-- Provides confidence scores (low confidence → escalate to LLM)
+- 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.
@@ -44,6 +46,7 @@ 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
+- **Hierarchical tool architecture**: Brain handles sub-agent routing (orchestrator → sub-agents with specialized tool sets)
 
 It's like a hive mind for AI agents — practical distributed learning at scale.
 
@@ -78,10 +81,35 @@ see → simulate outcomes → pick best action → act
 
 ---
 
+## Authentication & Keys
+
+### Zero-Config (Formation Pool)
+No API key needed. Formation holds pooled OpenRouter keys as a universal fallback.
+- 25% markup on usage
+- Instant access to all 2050+ models on day 0
+- No setup required
+
+### BYOK (Bring Your Own Key)
+Set `STRATUS_API_KEY` to bypass the Formation pool (no markup).
+- Keys must start with `stratus_sk_`
+- Get yours at https://stratus.run
+
+### Inline Provider Keys
+Pass provider keys per-request for direct BYOK passthrough:
+- `openai_key` — OpenAI direct
+- `anthropic_key` — Anthropic direct
+- `gemini_key` — Google Gemini direct (also sent as `X-Google-Key` header)
+- Three-tier priority: headers > body > vault
+
+Responses include `key_source: "user"` or `key_source: "formation"` so you always know which path was used.
+
+---
+
 ## Available Models
 
-Stratus provides **75 models** in the format:
+Stratus provides **2050+ models** dynamically discovered via OpenRouter at startup.
 
+Model format:
 ```
 stratus-x1ac-{size}-{llm}
 ```
@@ -89,9 +117,10 @@ 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
+- `claude-sonnet-4-5` — Claude 4.5 Sonnet (recommended)
+- `gpt-4o` — GPT-4 Optimized
+- `claude-haiku-4-5` — Fast, cost-effective
+- `gemini-2.0-flash` — High context, fast
 
 **Example:**
 ```bash
@@ -99,6 +128,8 @@ openclaw agent "Plan a multi-step research task" \
   --model stratus/stratus-x1ac-base-claude-sonnet-4-5
 ```
 
+Use `/stratus models` to fetch the full live list from the API.
+
 ---
 
 ## Available Tools
@@ -121,7 +152,7 @@ Generate 768-dimensional semantic state embeddings.
 ```
 
 ### `stratus_rollout`
-Multi-step action sequence planning.
+Multi-step action sequence planning via Policy Head v3.
 
 **Use cases:**
 - Task decomposition
@@ -129,6 +160,12 @@ Multi-step action sequence planning.
 - Goal-oriented reasoning
 - Multi-step workflows
 
+**Response fields:**
+- `steps` — ordered action sequence
+- `metadata.brain_confidence` — how confident the brain is in the plan
+- `metadata.brain_goal_proximity` — estimated closeness to goal state
+- `metadata.key_source` — "user" or "formation"
+
 **Example:**
 ```typescript
 {
@@ -162,6 +199,27 @@ const response = await openai.chat.completions.create({
 
 Stratus handles planning, then routes execution to the specified LLM (GPT-4o, Claude, etc.).
 
+Non-Stratus models (e.g. raw `gpt-4o`) bypass the world model pipeline entirely (LLM passthrough).
+
+Tool limit: **1024 tools per request** (raised from 100).
+
+---
+
+## SDKs
+
+- **TypeScript**: This OpenClaw plugin (`@formthefog/stratus`)
+- **Python**: `pip install stratus-sdk-py` (v0.0.6, full TS SDK parity, 76 tests)
+- **Pi Agent**: `pi-formation` package (7 curated X1-AC models for Pi coding agent)
+
+---
+
+## Billing
+
+- **Signup credits**: 200 credits (20K units) for new users
+- **Saved cards**: Stripe-backed auto top-up when balance is low
+- **Subscriptions**: Monthly credit bundles (starter/pro/enterprise) — 25% more credits vs one-time
+- **Formation pool**: 25% markup on pooled key usage; BYOK users pay no markup
+
 ---
 
 ## Common Misconceptions
@@ -171,6 +229,7 @@ Stratus handles planning, then routes execution to the specified LLM (GPT-4o, Cl
 | "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 |
+| "You need an API key" | Formation pool provides zero-config access; BYOK is optional |
 
 ---
 
@@ -187,10 +246,10 @@ For full technical details, see:
 
 1. **Install plugin:**
    ```bash
-   openclaw plugins install @hathbanger/stratus
+   openclaw plugins install @formthefog/stratus
    ```
 
-2. **Set API key:**
+2. **(Optional) Set API key for BYOK:**
    ```bash
    export STRATUS_API_KEY=stratus_sk_your_key_here
    ```
@@ -215,6 +274,7 @@ For full technical details, see:
 - Research workflows
 - Complex decision-making with uncertain outcomes
 - Tasks requiring "what-if" simulation
+- Large tool sets (up to 1024 tools)
 
 **Overkill for:**
 - Simple Q&A

package/src/client.ts

@@ -1,6 +1,7 @@
 import type {
   StratusEmbeddingsRequest,
   StratusEmbeddingsResponse,
+  StratusInlineKeys,
   StratusPluginConfig,
   StratusRolloutRequest,
   StratusRolloutResponse,
@@ -10,44 +11,74 @@ import type {
  * SECURITY MANIFEST
  *
  * Environment Variables Accessed:
- * - STRATUS_API_KEY: User's Stratus API key (optional, can use config instead)
+ * - STRATUS_API_KEY: User's Stratus API key (optional — Formation pool used as fallback)
+ * - OPENAI_API_KEY: Optional inline key for BYOK passthrough
+ * - ANTHROPIC_API_KEY: Optional inline key for BYOK passthrough
+ * - GOOGLE_API_KEY: Optional inline key for BYOK passthrough (also sent as X-Google-Key header)
  *
  * Network Endpoints:
  * - https://api.stratus.run/v1/embeddings (POST)
  * - https://api.stratus.run/v1/rollout (POST)
+ * - https://api.stratus.run/v1/models (GET)
  *
  * Data Transmitted:
- * - Authorization header: Bearer token (Stratus API key)
- * - Request body: User-provided text, goals, and parameters
+ * - Authorization header: Bearer token (Stratus API key, when provided)
+ * - X-Google-Key header: Google API key (when provided)
+ * - Request body: User-provided text, goals, parameters, and optional inline LLM keys
  *
  * 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_')
+ * - API key validated when present (must start with 'stratus_sk_')
+ * - Keyless operation uses Formation pooled keys (25% markup)
  * - HTTPS-only connections
  * - Keys never logged or persisted to disk by this plugin
  */
 
 export interface StratusClientConfig {
-  apiKey: string;
+  apiKey?: string;
   baseUrl: string;
+  inlineKeys?: StratusInlineKeys;
 }
 
 export class StratusClient {
   constructor(private config: StratusClientConfig) {}
 
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+
+    if (this.config.inlineKeys?.gemini_key) {
+      headers["X-Google-Key"] = this.config.inlineKeys.gemini_key;
+    }
+
+    return headers;
+  }
+
+  private buildInlineKeyBody(): Record<string, string> {
+    const body: Record<string, string> = {};
+    if (this.config.inlineKeys?.openai_key) body.openai_key = this.config.inlineKeys.openai_key;
+    if (this.config.inlineKeys?.anthropic_key) body.anthropic_key = this.config.inlineKeys.anthropic_key;
+    if (this.config.inlineKeys?.gemini_key) body.gemini_key = this.config.inlineKeys.gemini_key;
+    return body;
+  }
+
   private async request<T>(endpoint: string, body: unknown): Promise<T> {
     const url = `${this.config.baseUrl}${endpoint}`;
+    const inlineKeys = this.buildInlineKeyBody();
+    const mergedBody = { ...(body as Record<string, unknown>), ...inlineKeys };
 
     const response = await fetch(url, {
       method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
+      headers: this.buildHeaders(),
+      body: JSON.stringify(mergedBody),
     });
 
     if (!response.ok) {
@@ -76,23 +107,52 @@ export class StratusClient {
       return_intermediate: params.return_intermediate ?? true,
     });
   }
+
+  async listModels(): Promise<{ object: string; data: Array<{ id: string; object: string; created: number; owned_by: string }> }> {
+    const url = `${this.config.baseUrl}/v1/models`;
+    const headers: Record<string, string> = {};
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Stratus API error (${response.status}): ${errorText || response.statusText}`,
+      );
+    }
+
+    return response.json();
+  }
 }
 
 export function createStratusClient(config: StratusPluginConfig | undefined): StratusClient {
   const apiKey = config?.apiKey || process.env.STRATUS_API_KEY;
   const baseUrl = config?.baseUrl || "https://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_")) {
+  if (apiKey && !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 });
+  const inlineKeys: StratusInlineKeys = {
+    ...config?.inlineKeys,
+    openai_key: config?.inlineKeys?.openai_key || process.env.OPENAI_API_KEY,
+    anthropic_key: config?.inlineKeys?.anthropic_key || process.env.ANTHROPIC_API_KEY,
+    gemini_key: config?.inlineKeys?.gemini_key || process.env.GOOGLE_API_KEY,
+  };
+
+  const hasAnyInlineKey = inlineKeys.openai_key || inlineKeys.anthropic_key || inlineKeys.gemini_key;
+
+  return new StratusClient({
+    apiKey: apiKey || undefined,
+    baseUrl,
+    inlineKeys: hasAnyInlineKey ? inlineKeys : undefined,
+  });
 }

package/src/config.ts

@@ -3,12 +3,18 @@ import type { StratusPluginConfig } from "./types.js";
 
 export const StratusConfigSchema: OpenClawPluginConfigSchema = {
   parse(value: unknown): StratusPluginConfig {
-    const raw =
+    const entry =
       value && typeof value === "object" && !Array.isArray(value)
         ? (value as Record<string, unknown>)
         : {};
 
-    const enabled = typeof raw.enabled === "boolean" ? raw.enabled : true;
+    const enabled = typeof entry.enabled === "boolean" ? entry.enabled : true;
+
+    const raw =
+      entry.config && typeof entry.config === "object" && !Array.isArray(entry.config)
+        ? (entry.config as Record<string, unknown>)
+        : {};
+
     const apiKey = typeof raw.apiKey === "string" ? raw.apiKey : process.env.STRATUS_API_KEY;
     const baseUrl = typeof raw.baseUrl === "string" ? raw.baseUrl : "https://api.stratus.run";
 
@@ -37,10 +43,22 @@ export const StratusConfigSchema: OpenClawPluginConfigSchema = {
         ? (tools.rollout as Record<string, unknown>)
         : {};
 
+    const inlineKeysRaw =
+      raw.inlineKeys && typeof raw.inlineKeys === "object" && !Array.isArray(raw.inlineKeys)
+        ? (raw.inlineKeys as Record<string, unknown>)
+        : {};
+
+    const inlineKeys = {
+      openai_key: typeof inlineKeysRaw.openai_key === "string" ? inlineKeysRaw.openai_key : undefined,
+      anthropic_key: typeof inlineKeysRaw.anthropic_key === "string" ? inlineKeysRaw.anthropic_key : undefined,
+      gemini_key: typeof inlineKeysRaw.gemini_key === "string" ? inlineKeysRaw.gemini_key : undefined,
+    };
+
     return {
       enabled,
       apiKey,
       baseUrl,
+      inlineKeys,
       provider: {
         enabled: providerEnabled,
         defaultModel,
@@ -57,14 +75,17 @@ export const StratusConfigSchema: OpenClawPluginConfigSchema = {
   },
   uiHints: {
     enabled: { label: "Enabled" },
-    apiKey: { label: "API Key", sensitive: true },
-    baseUrl: { label: "Base URL", placeholder: "https://api.stratus.run" },
-    "provider.enabled": { label: "Provider Enabled" },
-    "provider.defaultModel": {
+    "config.apiKey": { label: "API Key", sensitive: true },
+    "config.baseUrl": { label: "Base URL", placeholder: "https://api.stratus.run" },
+    "config.inlineKeys.openai_key": { label: "OpenAI Key (BYOK)", sensitive: true },
+    "config.inlineKeys.anthropic_key": { label: "Anthropic Key (BYOK)", sensitive: true },
+    "config.inlineKeys.gemini_key": { label: "Google Gemini Key (BYOK)", sensitive: true },
+    "config.provider.enabled": { label: "Provider Enabled" },
+    "config.provider.defaultModel": {
       label: "Default Model",
       placeholder: "stratus-x1ac-base-claude-sonnet-4-5",
     },
-    "tools.embeddings.enabled": { label: "Embeddings Tool Enabled" },
-    "tools.rollout.enabled": { label: "Rollout Tool Enabled" },
+    "config.tools.embeddings.enabled": { label: "Embeddings Tool Enabled" },
+    "config.tools.rollout.enabled": { label: "Rollout Tool Enabled" },
   },
 };

package/src/setup.ts

@@ -18,31 +18,28 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
   const details: string[] = [];
 
   try {
-    // Step 1: Check for existing API key
     const apiKey = process.env.STRATUS_API_KEY;
-
-    if (!apiKey) {
-      return {
-        success: false,
-        message: "STRATUS_API_KEY not found",
-        details: [
-          "Please set your Stratus API key as an environment variable:",
-          "",
-          "  export STRATUS_API_KEY=stratus_sk_your_key_here",
-          "",
-          "Or add to your shell config (~/.zshrc or ~/.bashrc):",
-          "",
-          "  echo 'export STRATUS_API_KEY=stratus_sk_your_key_here' >> ~/.zshrc",
-          "  source ~/.zshrc",
-          "",
-          "Get your API key at: https://stratus.run",
-        ],
-      };
+    const usingFormationPool = !apiKey;
+
+    if (apiKey) {
+      if (!apiKey.startsWith("stratus_sk_")) {
+        return {
+          success: false,
+          message: "Invalid STRATUS_API_KEY format",
+          details: [
+            "API key must start with 'stratus_sk_'",
+            "",
+            "Get your API key at: https://stratus.run",
+          ],
+        };
+      }
+      details.push("✓ Using STRATUS_API_KEY from environment (BYOK — no markup)");
+    } else {
+      details.push("✓ No API key found — using Formation pooled keys (zero-config)");
+      details.push("  ℹ  Formation pool applies a 25% markup on usage");
+      details.push("  💡 Set STRATUS_API_KEY for BYOK (no markup)");
     }
 
-    details.push("✓ Using STRATUS_API_KEY from environment");
-
-    // Paths
     const homeDir = os.homedir();
     const openclawConfig = path.join(homeDir, ".openclaw", "openclaw.json");
     const authProfiles = path.join(
@@ -54,25 +51,18 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
       "auth-profiles.json"
     );
 
-    // Step 2: Update OpenClaw config
     details.push("🔧 Updating OpenClaw configuration...");
 
     if (fs.existsSync(openclawConfig)) {
-      // Backup
       const backupPath = `${openclawConfig}.backup-${Date.now()}`;
       fs.copyFileSync(openclawConfig, backupPath);
       details.push(`  📦 Created backup: ${path.basename(backupPath)}`);
 
-      // Read and update config
       const config = JSON.parse(fs.readFileSync(openclawConfig, "utf-8"));
 
-      // Add models.providers.stratus if not present
-      if (!config.models) {
-        config.models = {};
-      }
-      if (!config.models.providers) {
-        config.models.providers = {};
-      }
+      if (!config.models) config.models = {};
+      if (!config.models.providers) config.models.providers = {};
+
       if (!config.models.providers.stratus) {
         config.models.providers.stratus = {
           baseUrl: "https://api.stratus.run/v1",
@@ -94,24 +84,11 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
         details.push("  ✓ Stratus provider already configured");
       }
 
-      // Add model alias
-      if (!config.agents?.defaults?.models) {
-        if (!config.agents) config.agents = {};
-        if (!config.agents.defaults) config.agents.defaults = {};
-        if (!config.agents.defaults.models) config.agents.defaults.models = {};
-      }
-
-      if (!config.agents.defaults.models["stratus/stratus-x1ac-base-claude-sonnet-4-5"]) {
-        config.agents.defaults.models["stratus/stratus-x1ac-base-claude-sonnet-4-5"] = {
-          alias: "stratus",
-          params: {},
-        };
-        details.push("  ✓ Added model alias 'stratus'");
-      } else {
-        details.push("  ✓ Model alias already configured");
+      if (config.agents?.defaults?.models?.["stratus/stratus-x1ac-base-claude-sonnet-4-5"]) {
+        delete config.agents.defaults.models["stratus/stratus-x1ac-base-claude-sonnet-4-5"];
+        details.push("  ✓ Removed restrictive model alias (allows all Stratus models)");
       }
 
-      // Write updated config
       fs.writeFileSync(openclawConfig, JSON.stringify(config, null, 2));
     } else {
       return {
@@ -125,7 +102,6 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
       };
     }
 
-    // Step 3: Update auth profiles
     details.push("🔑 Configuring authentication...");
 
     const authDir = path.dirname(authProfiles);
@@ -135,14 +111,10 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
 
     let authConfig: any;
     if (fs.existsSync(authProfiles)) {
-      // Backup
       const backupPath = `${authProfiles}.backup-${Date.now()}`;
       fs.copyFileSync(authProfiles, backupPath);
-
-      // Update existing
       authConfig = JSON.parse(fs.readFileSync(authProfiles, "utf-8"));
     } else {
-      // Create new
       authConfig = {
         version: 1,
         profiles: {},
@@ -151,16 +123,26 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
       };
     }
 
-    // Add Stratus profile
-    authConfig.profiles["stratus:default"] = {
-      type: "api_key",
-      provider: "stratus",
-      key: apiKey,
-    };
-    authConfig.lastGood.stratus = "stratus:default";
+    if (apiKey) {
+      authConfig.profiles["stratus:default"] = {
+        type: "api_key",
+        provider: "stratus",
+        key: apiKey,
+      };
+      authConfig.lastGood.stratus = "stratus:default";
+      details.push("  ✓ Updated auth profile (BYOK)");
+    } else {
+      authConfig.profiles["stratus:formation-pool"] = {
+        type: "formation_pool",
+        provider: "stratus",
+      };
+      authConfig.lastGood.stratus = "stratus:formation-pool";
+      details.push("  ✓ Configured Formation pool auth (zero-config)");
+    }
 
     fs.writeFileSync(authProfiles, JSON.stringify(authConfig, null, 2));
-    details.push("  ✓ Updated auth profile");
+
+    const modeLabel = usingFormationPool ? "Formation pool (zero-config)" : "BYOK (no markup)";
 
     return {
       success: true,
@@ -168,6 +150,8 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
       details: [
         ...details,
         "",
+        `🔒 Auth mode: ${modeLabel}`,
+        "",
         "🎯 Next steps:",
         "  1. Restart gateway: openclaw gateway stop && openclaw gateway install",
         "  2. Verify: openclaw models list | grep stratus",
@@ -176,6 +160,14 @@ export async function setupStratus(prompter?: any): Promise<SetupResult> {
         "📚 Available tools:",
         "  • stratus_embeddings - Generate semantic embeddings",
         "  • stratus_rollout - Multi-step task planning",
+        ...(usingFormationPool
+          ? [
+              "",
+              "💡 To remove the 25% Formation markup, set your own key:",
+              "   export STRATUS_API_KEY=stratus_sk_your_key_here",
+              "   Then re-run /stratus setup",
+            ]
+          : []),
       ],
     };
   } catch (error) {

package/src/types.ts

@@ -38,13 +38,24 @@ export interface StratusRolloutResponse {
   metadata?: {
     model: string;
     duration_ms?: number;
+    brain_confidence?: number;
+    brain_goal_proximity?: number;
+    key_source?: "user" | "formation";
+    formation_markup_applied?: number;
   };
 }
 
+export interface StratusInlineKeys {
+  openai_key?: string;
+  anthropic_key?: string;
+  gemini_key?: string;
+}
+
 export interface StratusPluginConfig {
   enabled?: boolean;
   apiKey?: string;
   baseUrl?: string;
+  inlineKeys?: StratusInlineKeys;
   provider?: {
     enabled?: boolean;
     defaultModel?: string;