@formthefog/stratus 2026.2.24 → 2026.3.19

package/README.md

@@ -10,10 +10,12 @@ Integrate Stratus V3 (X1-AC), a state-of-the-art action-conditioned JEPA (Joint-
 
 ## Features
 
-- **Model Provider**: Use Stratus models (GPT-4o or Claude Sonnet 4 backends) for agent conversations
+- **Zero-Config**: Works out of the box with Formation pooled keys — no API key needed
+- **2050+ Models**: Dynamic discovery via OpenRouter — OpenAI, Anthropic, Google, and more
+- **Model Provider**: Use Stratus models for agent conversations with predictive planning
 - **Embeddings Tool**: Generate 768-dimensional semantic state embeddings
-- **Rollout Tool**: Multi-step task planning with action sequence prediction
-- **Secure**: API key authentication with automatic validation
+- **Rollout Tool**: Multi-step task planning via Policy Head v3 (94.4% accuracy)
+- **BYOK Support**: Bring your own provider keys (`openai_key`, `anthropic_key`, `gemini_key`) for zero-markup usage
 - **Opt-in Tools**: Tools are optional and require explicit allowlisting
 
 > See [SECURITY.md](./SECURITY.md) for a full accounting of credentials accessed, network calls made, and files written.
@@ -26,23 +28,10 @@ Integrate Stratus V3 (X1-AC), a state-of-the-art action-conditioned JEPA (Joint-
 
 ## Installation
 
-### Quick Start (3 Steps) ✨
+### Quick Start (2 Steps) ✨
 
 > **Note:** This plugin does NOT have an automatic postinstall script. You must run setup manually.
 
-**Before you begin**, export your Stratus API key. Get one at [stratus.run](https://stratus.run).
-
-```bash
-export STRATUS_API_KEY=stratus_sk_your_key_here
-```
-
-To persist it across sessions, add it to your shell config:
-
-```bash
-echo 'export STRATUS_API_KEY=stratus_sk_your_key_here' >> ~/.zshrc
-source ~/.zshrc
-```
-
 ```bash
 # 1. Install the plugin
 openclaw plugins install @formthefog/stratus
@@ -54,64 +43,24 @@ openclaw plugins install @formthefog/stratus
 /stratus verify
 ```
 
-**That's it!** The `/stratus setup` command handles:
-- ✅ API key configuration
+**That's it!** No API key required — Formation pooled keys give you instant access to all 2050+ models.
+
+The `/stratus setup` command handles:
+- ✅ Zero-config auth via Formation pool (or BYOK if you have a key)
 - ✅ OpenClaw config updates
 - ✅ Auth profile creation
-- ✅ Model registration
+- ✅ Dynamic model registration
 - ✅ Gateway restart prompt
 
 **No manual config editing required!** 🧈
 
-> **Tip:** Once installed, you can also access Stratus models with `/model stratus` in chat.
-
----
-
-## Using the API directly
-
-Stratus is drop-in compatible with OpenAI and Anthropic SDKs. Just change the `baseURL` and use your `STRATUS_API_KEY`.
-
-**OpenAI SDK (TypeScript)**
-```typescript
-import OpenAI from 'openai';
-
-const client = new OpenAI({
-  baseURL: 'https://api.stratus.run/v1',
-  apiKey: process.env.STRATUS_API_KEY
-});
-
-const response = await client.chat.completions.create({
-  model: 'stratus-x1ac-base-claude-sonnet-4-5',
-  messages: [{ role: 'user', content: 'Plan a route through 20 cities' }]
-});
-```
-
-**Anthropic SDK (TypeScript)**
-```typescript
-import Anthropic from '@anthropic-ai/sdk';
-
-const client = new Anthropic({
-  baseURL: 'https://api.stratus.run/v1',
-  apiKey: process.env.STRATUS_API_KEY
-});
-
-const response = await client.messages.create({
-  model: 'stratus-x1ac-base-claude-sonnet-4-5',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Plan a route through 20 cities' }]
-});
-```
+> **Optional — BYOK (no markup):** Set `STRATUS_API_KEY` to bypass the Formation pool:
+> ```bash
+> export STRATUS_API_KEY=stratus_sk_your_key_here
+> ```
+> Then re-run `/stratus setup`.
 
-**cURL**
-```bash
-curl https://api.stratus.run/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $STRATUS_API_KEY" \
-  -d '{
-    "model": "stratus-x1ac-base-claude-sonnet-4-5",
-    "messages": [{ "role": "user", "content": "Plan a route through 20 cities" }]
-  }'
-```
+> **Tip:** Once installed, you can also access Stratus models with `/model stratus` in chat.
 
 ---
 
@@ -124,6 +73,7 @@ Use these slash commands in any OpenClaw chat (TUI, Telegram, Discord, etc.):
 | `/stratus` | Show help |
 | `/stratus setup` | Interactive configuration wizard |
 | `/stratus verify` | Verify plugin is configured correctly |
+| `/stratus models` | List all available models (live from API) |
 
 ---
 
@@ -131,11 +81,11 @@ Use these slash commands in any OpenClaw chat (TUI, Telegram, Discord, etc.):
 
 The interactive setup command will:
 
-1. ✅ Prompt for your Stratus API key
+1. ✅ Detect auth mode (BYOK if `STRATUS_API_KEY` is set, Formation pool otherwise)
 2. ✅ Update OpenClaw configuration
 3. ✅ Configure authentication profiles
-4. ✅ Add model aliases
-5. ✅ (Optional) Add environment variables to your shell config
+4. ✅ Dynamically register all available models from the API
+5. ✅ Report auth mode and markup status
 
 ---
 
@@ -214,23 +164,41 @@ Edit `~/.openclaw/openclaw.json`:
 ```json
 {
   "plugins": {
-    "stratus": {
-      "enabled": true,
-      "apiKey": "${STRATUS_API_KEY}",
-      "baseUrl": "https://api.stratus.run",
-      "provider": {
+    "entries": {
+      "stratus": {
         "enabled": true,
-        "defaultModel": "stratus-x1ac-base-claude-sonnet-4-5"
-      },
-      "tools": {
-        "embeddings": { "enabled": true },
-        "rollout": { "enabled": true }
+        "config": {
+          "apiKey": "${STRATUS_API_KEY}",
+          "baseUrl": "https://api.stratus.run",
+          "inlineKeys": {
+            "openai_key": "${OPENAI_API_KEY}",
+            "anthropic_key": "${ANTHROPIC_API_KEY}",
+            "gemini_key": "${GOOGLE_API_KEY}"
+          },
+          "provider": {
+            "enabled": true,
+            "defaultModel": "stratus-x1ac-base-claude-sonnet-4-5"
+          },
+          "tools": {
+            "embeddings": { "enabled": true },
+            "rollout": { "enabled": true }
+          }
+        }
       }
     }
   }
 }
 ```
 
+> **Note:** All keys are optional. Without any keys, Formation pooled keys are used automatically (25% markup). Inline provider keys (`openai_key`, `anthropic_key`, `gemini_key`) let you BYOK for specific providers while using the pool for others.
+
+> **Important:** OpenClaw's plugin config schema requires plugin-specific settings
+> to be nested under a `config` key within `plugins.entries.<id>`. Only `enabled`
+> and `config` are valid top-level keys per entry. Placing keys like `apiKey` or
+> `tools` at the top level will cause a config validation error and prevent the
+> gateway from starting.
+```
+
 ## Usage
 
 ### 1. Use Stratus as a Model Provider
@@ -251,9 +219,9 @@ openclaw agent --model stratus/stratus-x1ac-small-claude-haiku-4-5 \
   "Quick question: what is JEPA?"
 ```
 
-**Available Models: 75 Total**
+**Available Models: Dynamic (2050+ models)**
 
-The plugin registers all 75 Stratus chat completion models:
+Models are fetched live from the Stratus API on startup via OpenRouter dynamic discovery and refreshed automatically. Run `/stratus models` to see the current full list. The plugin supports all models returned by the API.
 
 **Model Format:** `stratus-x1ac-{size}-{llm}`
 
@@ -269,9 +237,12 @@ The plugin registers all 75 Stratus chat completion models:
 
 **Anthropic LLMs (Claude 4.x):**
 
+- `claude-sonnet-4-6` - Claude 4.6 Sonnet (latest)
+- `claude-opus-4-6` - Claude 4.6 Opus (latest, high performance)
 - `claude-sonnet-4-5` - Claude 4.5 Sonnet (recommended)
 - `claude-opus-4-5` - Claude 4.5 Opus
 - `claude-haiku-4-5` - Claude 4.5 Haiku (fast)
+- `claude-opus-4-1` - Claude 4.1 Opus
 - `claude-sonnet-4` - Claude 4 Sonnet
 - `claude-opus-4` - Claude 4 Opus
 
@@ -279,11 +250,20 @@ The plugin registers all 75 Stratus chat completion models:
 
 - `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`
 
+**Google LLMs:**
+
+- `gemini-2.0-flash` - Gemini 2.0 Flash (1M context)
+- `gemini-1.5-pro` - Gemini 1.5 Pro (2M context)
+- `gemini-1.5-flash` - Gemini 1.5 Flash (1M context)
+- `gemini-pro` - Gemini Pro
+
 **Examples:**
 
 - `stratus/stratus-x1ac-base-claude-sonnet-4-5` (recommended)
+- `stratus/stratus-x1ac-base-claude-sonnet-4-6` (latest Claude)
 - `stratus/stratus-x1ac-base-gpt-4o`
-- `stratus/stratus-x1ac-large-claude-opus-4-5` (high performance)
+- `stratus/stratus-x1ac-base-gemini-2.0-flash` (1M context window)
+- `stratus/stratus-x1ac-large-claude-opus-4-6` (high performance)
 - `stratus/stratus-x1ac-small-gpt-4o-mini` (development/testing)
 
 ### 2. Use Stratus Tools
@@ -467,17 +447,9 @@ Tools are **opt-in only**:
 
 ### Quick Fixes
 
-#### "Stratus API key not configured"
-
-**Solution**:
-
-```bash
-export STRATUS_API_KEY=stratus_sk_live_your_key_here
-```
-
 #### "Invalid Stratus API key format"
 
-**Solution**: Verify your API key from stratus.run starts with `stratus_sk_`.
+**Solution**: If you set `STRATUS_API_KEY`, verify it starts with `stratus_sk_`. Or remove it entirely to use Formation pool (zero-config).
 
 #### "Tool not available"
 
@@ -523,18 +495,32 @@ This follows UNIX philosophy: clean separation, composable interfaces, transpare
 
 ### Configuration Schema
 
+OpenClaw plugin entries use `{ enabled, config }` at the top level. The `config`
+object holds all plugin-specific settings:
+
 ```typescript
+// What OpenClaw stores in plugins.entries.stratus
+interface PluginEntryConfig {
+  enabled?: boolean;
+  config?: StratusPluginConfig;
+}
+
+// Plugin-specific config (nested under "config" key)
 interface StratusPluginConfig {
-  enabled: boolean; // Enable plugin
-  apiKey: string; // API key (or env var)
-  baseUrl: string; // API base URL
-  provider: {
-    enabled: boolean; // Enable provider registration
-    defaultModel: string; // Default model
+  apiKey?: string;   // API key (optional — Formation pool used as fallback)
+  baseUrl?: string;  // API base URL
+  inlineKeys?: {     // BYOK keys passed per-request
+    openai_key?: string;
+    anthropic_key?: string;
+    gemini_key?: string;  // Also sent as X-Google-Key header
+  };
+  provider?: {
+    enabled?: boolean;     // Enable provider registration
+    defaultModel?: string; // Default model
   };
-  tools: {
-    embeddings: { enabled: boolean };
-    rollout: { enabled: boolean };
+  tools?: {
+    embeddings?: { enabled?: boolean };
+    rollout?: { enabled?: boolean };
   };
 }
 ```

package/SECURITY.md

@@ -9,21 +9,24 @@
 ## Credentials
 
 **What is accessed:**
-- `STRATUS_API_KEY` — read from environment or OpenClaw config (`plugins.stratus.apiKey`)
+- `STRATUS_API_KEY` — read from environment or OpenClaw config (`plugins.stratus.apiKey`). **Optional** — if not set, Formation pooled keys are used automatically.
+- `OPENAI_API_KEY` — optional, forwarded as inline BYOK key in request body
+- `ANTHROPIC_API_KEY` — optional, forwarded as inline BYOK key in request body
+- `GOOGLE_API_KEY` — optional, forwarded as inline BYOK key in request body and as `X-Google-Key` header
 
 **What is validated:**
-- Key must be present before any network call is made
-- Key must match the format `stratus_sk_*` — requests with malformed keys are rejected locally, no network call is made
+- If `STRATUS_API_KEY` is present, it must match the format `stratus_sk_*` — requests with malformed keys are rejected locally, no network call is made
+- If no key is present, the plugin operates in Formation pool mode (zero-config, 25% markup)
 
 **What is written to disk:**
-- During setup, the API key is stored in `~/.openclaw/agents/main/agent/auth-profiles.json`
+- During setup, the auth profile is stored in `~/.openclaw/agents/main/agent/auth-profiles.json`
 - This is the standard OpenClaw credential store, equivalent in scope to `~/.aws/credentials` or `~/.npmrc`
 - A timestamped backup of any existing file is created before writing
-- The key is never logged, printed, or written anywhere else by this plugin
+- Keys are never logged, printed, or written anywhere else by this plugin
 
 **What is never accessed:**
 - `~/.ssh` or any SSH keys or known_hosts — nothing in this plugin reads or touches SSH paths
-- Other environment variables beyond `STRATUS_API_KEY`, `STRATUS_BASE_URL`, and `SHELL`
+- Other environment variables beyond `STRATUS_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `STRATUS_BASE_URL`, and `SHELL`
 - Browser storage, keychains, or system credential managers
 
 ---
@@ -33,8 +36,17 @@
 **Outbound endpoints:**
 | Endpoint | When | What is sent |
 |---|---|---|
-| `https://api.stratus.run/v1/embeddings` | `stratus_embeddings` tool call | `Authorization: Bearer <key>`, text input |
-| `https://api.stratus.run/v1/rollout` | `stratus_rollout` tool call | `Authorization: Bearer <key>`, goal + state |
+| `https://api.stratus.run/v1/embeddings` | `stratus_embeddings` tool call | `Authorization: Bearer <key>` (if set), text input, optional inline keys |
+| `https://api.stratus.run/v1/rollout` | `stratus_rollout` tool call | `Authorization: Bearer <key>` (if set), goal + state, optional inline keys |
+| `https://api.stratus.run/v1/models` | Plugin startup / `/stratus models` | `Authorization: Bearer <key>` (if set) |
+
+**Headers sent:**
+- `Authorization: Bearer <key>` — only when `STRATUS_API_KEY` is configured
+- `X-Google-Key: <key>` — only when a Google/Gemini key is configured
+- `Content-Type: application/json` — on all POST requests
+
+**Inline key fields in request body:**
+- `openai_key`, `anthropic_key`, `gemini_key` — only when corresponding environment variables or config values are set
 
 **What is never done:**
 - No calls to any endpoint other than `api.stratus.run`
@@ -55,10 +67,9 @@ Data handling is governed by the [Stratus privacy policy](https://stratus.run/pr
 
 **Files written during setup:**
 - Same paths as above, plus timestamped `.backup-*` copies before any modification
-- Optionally appends `export STRATUS_API_KEY=...` to `~/.zshrc` / `~/.bashrc` / `~/.bash_profile` — only when the user explicitly answers `y` at the prompt
 
 **What is never touched:**
-- No files outside `~/.openclaw/`, the shell config the user selects, or the LaunchAgent plist
+- No files outside `~/.openclaw/` or the LaunchAgent plist
 - No `/etc/`, `/usr/`, `/Library/` (system paths)
 - No other dotfiles or home directory contents
 

package/TROUBLESHOOTING.md

@@ -132,9 +132,9 @@ Implement Option 1 (plugin-level role mapping) as it provides maximum compatibil
 
 ### "Stratus API key not configured"
 
-**Cause**: No API key found in config or environment.
+**Note**: As of March 2026, an API key is **no longer required**. The plugin uses Formation pooled keys by default (zero-config, 25% markup). This error should no longer appear.
 
-**Solution**:
+If you want BYOK (no markup), set your key:
 
 ```bash
 export STRATUS_API_KEY=stratus_sk_live_your_key_here