@formthefog/stratus 2026.2.17

package/TROUBLESHOOTING.md

@@ -0,0 +1,245 @@
+# Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### Silent Fallback to Anthropic (SIGBART ignores Stratus config)
+
+**Symptoms:**
+- SIGBART says "NOW RUNNING: Anthropic (Claude Opus 4.5)"
+- Stratus API key configured in `~/.openclaw/openclaw.json`
+- No obvious errors in logs
+- OpenClaw gateway running normally
+
+**Root Cause:**
+OpenClaw maintains **TWO separate locations** for API authentication:
+
+1. **Config file** (`~/.openclaw/openclaw.json`) - What you edit
+2. **Auth cache** (`~/.openclaw/agents/main/agent/auth-profiles.json`) - What the gateway actually uses
+
+**The config file does NOT automatically sync to the auth cache.**
+
+**Solution:**
+
+1. Update both files with your Stratus API key:
+
+```bash
+# 1. Update config (you probably already did this)
+vim ~/.openclaw/openclaw.json
+
+# 2. Update auth cache (THIS IS CRITICAL)
+vim ~/.openclaw/agents/main/agent/auth-profiles.json
+```
+
+2. In `auth-profiles.json`, add or update the Stratus profile:
+
+```json
+{
+  "profiles": [
+    {
+      "provider": "stratus",
+      "baseUrl": "https://dev.api.stratus.run/v1",
+      "apiKey": "stratus_sk_your_actual_key_here"
+    }
+  ]
+}
+```
+
+3. Restart OpenClaw gateway:
+
+```bash
+openclaw gateway restart
+```
+
+4. Verify auth is working with manual curl:
+
+```bash
+curl https://dev.api.stratus.run/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer stratus_sk_your_actual_key_here" \
+  -d '{
+    "model": "stratus-x1ac-base-claude-sonnet-4-5",
+    "messages": [{"role": "user", "content": "Test"}],
+    "max_tokens": 50
+  }'
+```
+
+Expected: `200 OK` with a response and credit balance
+
+**Key Learning:**
+- Always check **both** config and auth cache files
+- Auth cache doesn't auto-sync from config
+- 401 Unauthorized = auth cache issue, not endpoint issue
+- Use manual curl to verify auth independently
+
+**Verification Success (2026-02-15):**
+After fixing the auth cache issue:
+- ✅ API endpoint responding: `dev.api.stratus.run`
+- ✅ Authentication working: API key validated
+- ✅ User balance confirmed: 17784.00 credits
+- ✅ Model available: `stratus-x1ac-base-claude-sonnet-4-5`
+- ❌ **Next blocker**: Role field compatibility (see section below)
+
+---
+
+### Role Field Compatibility Issue
+
+**Symptoms:**
+- OpenClaw sends `role: "developer"` in messages
+- Stratus API returns error: `"messages: Unexpected role 'developer'. Allowed roles are 'user' or 'assistant'"`
+- May see validation errors about invalid role values
+
+**Root Cause:**
+OpenClaw uses Anthropic's `developer` role for system-level instructions, but the Stratus API (which wraps Anthropic's Messages API) expects only `user` or `assistant` roles. The `developer` role is Anthropic-specific but not supported when using the OpenAI-compatible `/v1/chat/completions` endpoint.
+
+**Impact:**
+After successfully authenticating and verifying API key/balance, actual chat completion requests fail with role validation errors.
+
+**Current Status (2026-02-15):**
+✅ **Authentication working** - API key verified, user balance confirmed (17784.00 credits)
+❌ **Chat completions blocked** - Role field validation prevents actual usage
+🔧 **Fix needed** - Plugin must transform `developer` → `system` for OpenAI-compatible providers
+
+**Solution Options:**
+
+**Option 1: Patch Stratus Plugin (RECOMMENDED)** ✅
+Add role mapping in the OpenClaw Stratus plugin before sending to API:
+
+```typescript
+// In src/client.ts
+function normalizeRole(role: string): string {
+  // Map Anthropic-specific roles to OpenAI-compatible roles
+  if (role === 'developer') return 'system';
+  return role;
+}
+
+// Then in chat completion method:
+const normalizedMessages = messages.map(msg => ({
+  ...msg,
+  role: normalizeRole(msg.role)
+}));
+```
+
+**Option 2: File OpenClaw Bug**
+Request OpenClaw core to handle role mapping for `openai-completions` API format providers automatically.
+
+**Option 3: Use Anthropic Messages API**
+Switch from `/v1/chat/completions` (OpenAI format) to `/v1/messages` (native Anthropic format), which natively supports the `developer` role.
+
+**Recommended Path:**
+Implement Option 1 (plugin-level role mapping) as it provides maximum compatibility and doesn't depend on upstream changes.
+
+---
+
+### "Stratus API key not configured"
+
+**Cause**: No API key found in config or environment.
+
+**Solution**:
+
+```bash
+export STRATUS_API_KEY=stratus_sk_live_your_key_here
+```
+
+Or run the setup wizard:
+
+```
+/stratus setup
+```
+
+---
+
+### "Invalid Stratus API key format"
+
+**Cause**: API key doesn't start with `stratus_sk_`.
+
+**Solution**: Verify your API key from [stratus.run](https://stratus.run).
+
+---
+
+### "Tool not available"
+
+**Cause**: Tool not in allowlist.
+
+**Solution**:
+
+```bash
+openclaw config set agents.defaults.tools.allow '["stratus_embeddings", "stratus_rollout"]'
+```
+
+---
+
+### "Stratus API error (401)"
+
+**Cause**: Invalid, expired, or cached API key.
+
+**Solution**:
+
+1. Get a new API key from [stratus.run](https://stratus.run)
+2. Update BOTH config files:
+   - `~/.openclaw/openclaw.json`
+   - `~/.openclaw/agents/main/agent/auth-profiles.json`
+3. Restart gateway: `openclaw gateway restart`
+
+---
+
+### "Stratus API error (429)"
+
+**Cause**: Rate limit exceeded.
+
+**Solution**: Wait and retry, or upgrade your Stratus plan.
+
+---
+
+## Debugging Checklist
+
+When Stratus integration isn't working:
+
+1. **Verify API key format**: Should start with `stratus_sk_`
+2. **Check config file**: `cat ~/.openclaw/openclaw.json | grep stratus`
+3. **Check auth cache**: `cat ~/.openclaw/agents/main/agent/auth-profiles.json`
+4. **Test with curl**: Use manual curl command (see above)
+5. **Check gateway logs**: `openclaw gateway logs`
+6. **Restart gateway**: `openclaw gateway restart`
+7. **Verify endpoint**: Should be `https://dev.api.stratus.run/v1`
+
+---
+
+## Known Issues
+
+### Auth Cache Staleness
+
+**Issue**: Changes to `openclaw.json` don't automatically sync to `auth-profiles.json`.
+
+**Impact**: Gateway continues using old/invalid credentials even after config update.
+
+**Workaround**: Manually update both files.
+
+**Future Enhancement**: OpenClaw should auto-sync config → auth cache on gateway restart.
+
+---
+
+### Role Field Mapping
+
+**Issue**: OpenClaw uses `developer` role, OpenAI uses `system` role.
+
+**Impact**: May cause validation errors with strict OpenAI-compatible APIs.
+
+**Workaround**: Stratus API now accepts `developer` role (deployed 2026-02-14).
+
+**Future Enhancement**: Plugin should map roles for maximum compatibility.
+
+---
+
+## Getting Help
+
+If none of these solutions work:
+
+1. Check gateway logs: `openclaw gateway logs`
+2. File an issue: [GitHub Issues](https://github.com/openclaw/openclaw/issues)
+3. Contact Stratus support: support@stratus.run
+
+Include in your report:
+- OpenClaw version: `openclaw --version`
+- Plugin version: `cat ~/.openclaw/plugins/stratus/package.json | grep version`
+- Relevant logs from `openclaw gateway logs`
+- Steps to reproduce

package/index.ts

@@ -0,0 +1,387 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { Type } from "@sinclair/typebox";
+import type { StratusPluginConfig } from "./src/types.js";
+import { createStratusClient } from "./src/client.js";
+import { StratusConfigSchema } from "./src/config.js";
+import { setupStratus } from "./src/setup.js";
+
+const PROVIDER_ID = "stratus";
+const PROVIDER_LABEL = "Stratus";
+const DEFAULT_BASE_URL = "https://dev.api.stratus.run/v1";
+
+function buildModelDefinition(params: {
+  id: string;
+  name: string;
+  contextWindow?: number;
+  maxTokens?: number;
+}) {
+  return {
+    id: params.id,
+    name: params.name,
+    reasoning: true,
+    input: ["text", "image"] as const,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: params.contextWindow || 128000,
+    maxTokens: params.maxTokens || 8192,
+  };
+}
+
+const STRATUS_SIZES = ["small", "base", "large", "xl", "huge"] as const;
+
+const OPENAI_MODELS = [
+  { id: "gpt-4o", name: "GPT-4o", context: 128000, tokens: 8192 },
+  { id: "gpt-4o-mini", name: "GPT-4o Mini", context: 128000, tokens: 8192 },
+  { id: "gpt-4-turbo", name: "GPT-4 Turbo", context: 128000, tokens: 4096 },
+  { id: "gpt-4", name: "GPT-4", context: 8192, tokens: 4096 },
+  { id: "gpt-3.5-turbo", name: "GPT-3.5 Turbo", context: 16385, tokens: 4096 },
+] as const;
+
+const ANTHROPIC_MODELS = [
+  { id: "claude-sonnet-4-5", name: "Claude 4.5 Sonnet", context: 200000, tokens: 8192 },
+  { id: "claude-opus-4-5", name: "Claude 4.5 Opus", context: 200000, tokens: 8192 },
+  { id: "claude-sonnet-4", name: "Claude 4 Sonnet", context: 200000, tokens: 8192 },
+  { id: "claude-opus-4", name: "Claude 4 Opus", context: 200000, tokens: 8192 },
+  { id: "claude-haiku-4-5", name: "Claude 4.5 Haiku", context: 200000, tokens: 8192 },
+  { id: "claude-3-7-sonnet", name: "Claude 3.7 Sonnet", context: 200000, tokens: 8192 },
+  { id: "claude-3-5-sonnet", name: "Claude 3.5 Sonnet", context: 200000, tokens: 8192 },
+  { id: "claude-3-opus", name: "Claude 3 Opus", context: 200000, tokens: 4096 },
+  { id: "claude-3-sonnet", name: "Claude 3 Sonnet", context: 200000, tokens: 4096 },
+  { id: "claude-3-haiku", name: "Claude 3 Haiku", context: 200000, tokens: 4096 },
+] as const;
+
+function generateAllModels() {
+  const models = [];
+
+  for (const size of STRATUS_SIZES) {
+    const sizeLabel = size.charAt(0).toUpperCase() + size.slice(1);
+
+    for (const llm of OPENAI_MODELS) {
+      models.push(
+        buildModelDefinition({
+          id: `stratus-x1ac-${size}-${llm.id}`,
+          name: `Stratus X1AC ${sizeLabel} (${llm.name})`,
+          contextWindow: llm.context,
+          maxTokens: llm.tokens,
+        }),
+      );
+    }
+
+    for (const llm of ANTHROPIC_MODELS) {
+      models.push(
+        buildModelDefinition({
+          id: `stratus-x1ac-${size}-${llm.id}`,
+          name: `Stratus X1AC ${sizeLabel} (${llm.name})`,
+          contextWindow: llm.context,
+          maxTokens: llm.tokens,
+        }),
+      );
+    }
+  }
+
+  return models;
+}
+
+const stratusPlugin = {
+  id: "stratus",
+  name: "Stratus API Integration",
+  description: "Stratus V3 (X1-AC) action-conditioned JEPA for autonomous agent planning",
+  configSchema: StratusConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    const pluginConfig = StratusConfigSchema.parse(api.pluginConfig) as StratusPluginConfig;
+
+    api.registerProvider({
+      id: PROVIDER_ID,
+      label: PROVIDER_LABEL,
+      docsPath: "/providers/stratus",
+      aliases: ["stratus-run"],
+      auth: [
+        {
+          id: "api-key",
+          label: "API Key",
+          kind: "api_key",
+          run: async (ctx) => {
+            const apiKey = await ctx.prompter.text({
+              message: "Enter your Stratus API key:",
+              validate: (val: string) => {
+                if (!val.trim()) {
+                  return "API key is required";
+                }
+                if (!val.startsWith("stratus_sk_")) {
+                  return "API key must start with 'stratus_sk_'";
+                }
+                return undefined;
+              },
+            });
+
+            const profileId = `${PROVIDER_ID}:default`;
+
+            return {
+              profiles: [
+                {
+                  profileId,
+                  credential: {
+                    type: "api_key",
+                    provider: PROVIDER_ID,
+                    key: apiKey,
+                  },
+                },
+              ],
+              configPatch: {
+                models: {
+                  providers: {
+                    [PROVIDER_ID]: {
+                      baseUrl: DEFAULT_BASE_URL,
+                      apiKey: apiKey,
+                      api: "openai-completions",
+                      models: generateAllModels(),
+                    },
+                  },
+                },
+                agents: {
+                  defaults: {
+                    models: {
+                      [`${PROVIDER_ID}/stratus-x1ac-base-claude-sonnet-4-5`]: {
+                        alias: "stratus",
+                      },
+                    },
+                  },
+                },
+              },
+              defaultModel: `${PROVIDER_ID}/stratus-x1ac-base-claude-sonnet-4-5`,
+              notes: [
+                "🌊 Stratus X1-AC: World Model + Collective Intelligence System",
+                "",
+                "NOT just an LLM wrapper — this is predictive planning:",
+                "  Traditional agents: see → think → act → see again",
+                "  Stratus agents: see → simulate outcomes → pick best → act",
+                "",
+                "Architecture:",
+                "  • World Model (X1): Predicts future states from actions (JEPA-based)",
+                "  • Policy Head (X1-AC): Selects optimal actions toward goals",
+                "  • Collective Network: Agents learn from each other in real-time",
+                "",
+                "Available Tools:",
+                "  • stratus_embeddings() - 768-dim semantic state embeddings",
+                "  • stratus_rollout() - Multi-step action sequence planning",
+                "",
+                "Learn more: /stratus-info (bundled skill)",
+                "Technical docs: https://stratus.run/docs/technical-overview",
+              ],
+            };
+          },
+        },
+      ],
+    });
+
+    if (!pluginConfig.tools?.embeddings?.enabled && !pluginConfig.tools?.rollout?.enabled) {
+      return;
+    }
+
+    if (pluginConfig.tools?.embeddings?.enabled) {
+      api.registerTool(
+        {
+          name: "stratus_embeddings",
+          label: "Stratus Embeddings",
+          description:
+            "Generate 768-dimensional state embeddings for semantic search and memory. Use this for understanding semantic relationships between states or actions.",
+          parameters: Type.Object({
+            input: Type.Union(
+              [
+                Type.String({ description: "Single text to embed" }),
+                Type.Array(Type.String(), { description: "Multiple texts to embed" }),
+              ],
+              { description: "Text or array of texts to generate embeddings for" },
+            ),
+            model: Type.Optional(
+              Type.String({
+                description: "Stratus model to use",
+                default: "stratus-x1ac-base",
+              }),
+            ),
+            encoding_format: Type.Optional(
+              Type.Union([Type.Literal("float"), Type.Literal("base64")], {
+                default: "float",
+                description: "Format for embedding vectors",
+              }),
+            ),
+          }),
+          async execute(_toolCallId, params, context) {
+            const client = createStratusClient(pluginConfig);
+
+            const response = await client.embeddings({
+              input: params.input,
+              model: params.model,
+              encoding_format: params.encoding_format,
+            });
+
+            const count = response.data.length;
+            const dimensions = Array.isArray(response.data[0]?.embedding)
+              ? response.data[0].embedding.length
+              : 768;
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Generated ${count} embedding${count === 1 ? "" : "s"} (${dimensions} dimensions each)\nModel: ${response.model}\nUsage: ${response.usage.prompt_tokens} tokens`,
+                },
+              ],
+              details: response,
+            };
+          },
+        },
+        { optional: true },
+      );
+    }
+
+    if (pluginConfig.tools?.rollout?.enabled) {
+      api.registerTool(
+        {
+          name: "stratus_rollout",
+          label: "Stratus Rollout",
+          description:
+            "Multi-step rollout prediction for task planning. Predicts action sequences to reach a goal state. Use this for complex task decomposition and planning.",
+          parameters: Type.Object({
+            goal: Type.String({
+              description: "Target state or goal to achieve (e.g., 'book a hotel room')",
+            }),
+            initial_state: Type.Optional(
+              Type.String({
+                description: "Starting state (optional, can be inferred from context)",
+              }),
+            ),
+            max_steps: Type.Optional(
+              Type.Number({
+                description: "Maximum rollout steps",
+                default: 10,
+                minimum: 1,
+                maximum: 50,
+              }),
+            ),
+            return_intermediate: Type.Optional(
+              Type.Boolean({
+                description: "Return intermediate states",
+                default: true,
+              }),
+            ),
+          }),
+          async execute(_toolCallId, params, context) {
+            const client = createStratusClient(pluginConfig);
+
+            const response = await client.rollout({
+              goal: params.goal,
+              initial_state: params.initial_state,
+              max_steps: params.max_steps,
+              return_intermediate: params.return_intermediate,
+            });
+
+            const steps = response.steps || [];
+            const stepText = steps
+              .map((s, i) => `${i + 1}. ${s.action || s.description || "Unknown step"}`)
+              .join("\n");
+
+            const summary = response.success
+              ? `Successfully planned ${steps.length} steps to reach goal`
+              : `Planning incomplete (${steps.length} steps generated)`;
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `${summary}\nGoal: ${response.goal}\n\nSteps:\n${stepText}`,
+                },
+              ],
+              details: response,
+            };
+          },
+        },
+        { optional: true },
+      );
+    }
+
+    // Register CLI commands
+    if (typeof api.registerCommand === "function") {
+      api.registerCommand({
+        name: "stratus",
+        description: "Stratus plugin commands (setup, verify)",
+        acceptsArgs: true,
+        handler: async (ctx: any) => {
+          const args = ctx.args?.trim() ?? "";
+          const tokens = args.split(/\s+/).filter(Boolean);
+          const subcommand = (tokens[0] || "help").toLowerCase();
+
+          if (subcommand === "setup") {
+            // Run setup
+            const result = await setupStratus(ctx.prompter);
+
+            if (result.success) {
+              console.log(`\n✅ ${result.message}\n`);
+              if (result.details) {
+                result.details.forEach((line) => console.log(line));
+              }
+            } else {
+              console.error(`\n❌ ${result.message}\n`);
+              if (result.details) {
+                result.details.forEach((line) => console.error(line));
+              }
+              process.exit(1);
+            }
+            return { text: "" }; // Return empty to avoid double output
+          } else if (subcommand === "verify") {
+            // Run verify
+            console.log("🔍 Verifying Stratus configuration...\n");
+
+            let errors = 0;
+
+            // Check 1: Environment variable
+            console.log("1️⃣  Checking STRATUS_API_KEY...");
+            if (process.env.STRATUS_API_KEY) {
+              console.log("   ✓ STRATUS_API_KEY is set");
+            } else {
+              console.log("   ❌ STRATUS_API_KEY not found");
+              errors++;
+            }
+
+            // Check 2: Config exists
+            console.log("\n2️⃣  Checking plugin configuration...");
+            if (pluginConfig.apiKey || process.env.STRATUS_API_KEY) {
+              console.log("   ✓ API key configured");
+            } else {
+              console.log("   ❌ API key not configured");
+              errors++;
+            }
+
+            console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+            if (errors === 0) {
+              console.log("✅ All checks passed!");
+              console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+              console.log("🎯 Try it out:");
+              console.log("   openclaw agent 'Hello Stratus!' --model stratus\n");
+            } else {
+              console.log(`❌ ${errors} issue(s) found`);
+              console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+              console.log("💡 Run: openclaw stratus setup\n");
+              process.exit(1);
+            }
+            return { text: "" }; // Return empty to avoid double output
+          } else {
+            // Show help
+            return {
+              text:
+                "🌊 Stratus X1-AC Plugin\n\n" +
+                "Commands:\n" +
+                "  /stratus setup   - Interactive setup wizard\n" +
+                "  /stratus verify  - Verify configuration\n\n" +
+                "Get your API key: https://stratus.run\n" +
+                "Docs: https://stratus.run/docs\n" +
+                "Issues: https://github.com/formthefog/openclaw-stratus-x1-plugin/issues",
+            };
+          }
+        },
+      });
+    }
+  },
+};
+
+export default stratusPlugin;