simmer-automaton 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Simmer API client for the automaton plugin.
+ * Thin wrapper around fetch — reads automaton state, skills registry.
+ */
+export interface AutomatonState {
+    initialized: boolean;
+    budget_usd: number;
+    spent_usd: number;
+    remaining_usd: number;
+    halted: boolean;
+    tier: string;
+    horizon_days: number;
+    started_at: string | null;
+}
+export interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    difficulty: string;
+    install: string;
+    clawhub_url: string;
+    requires: string[];
+    best_when: string | null;
+}
+export declare class SimmerApi {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    getAutomatonState(): Promise<AutomatonState>;
+    initAutomaton(budgetUsd: number, horizonDays?: number): Promise<unknown>;
+    halt(): Promise<unknown>;
+    resume(): Promise<unknown>;
+    getSkills(): Promise<{
+        skills: Skill[];
+        total: number;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,45 @@
+/**
+ * Simmer API client for the automaton plugin.
+ * Thin wrapper around fetch — reads automaton state, skills registry.
+ */
+export class SimmerApi {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl = "https://api.simmer.markets") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, opts) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...opts,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                ...(opts?.headers || {}),
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Simmer API ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    async getAutomatonState() {
+        return this.request("/api/sdk/automaton/state");
+    }
+    async initAutomaton(budgetUsd, horizonDays = 30) {
+        return this.request("/api/sdk/automaton/init", {
+            method: "POST",
+            body: JSON.stringify({ budget_usd: budgetUsd, horizon_days: horizonDays }),
+        });
+    }
+    async halt() {
+        return this.request("/api/sdk/automaton/halt", { method: "POST" });
+    }
+    async resume() {
+        return this.request("/api/sdk/automaton/resume", { method: "POST" });
+    }
+    async getSkills() {
+        return this.request("/api/sdk/skills");
+    }
+}

package/dist/bandit.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Epsilon-greedy bandit for skill selection.
+ * Ported from automaton.py — select_skills, _avg_reward, tier_max_skills, tier_effective_epsilon.
+ */
+export interface SkillState {
+    slug: string;
+    enabled: boolean;
+    timesSelected: number;
+    timesRewarded: number;
+    totalPnl: number;
+    consecutiveZeroSignals: number;
+    signalsFoundTotal: number;
+    tradesExecutedTotal: number;
+    lastCycle?: {
+        skipCounts?: Record<string, number>;
+    };
+}
+export interface SelectionMeta {
+    slug: string;
+    reason: string;
+    score: number | null;
+}
+export declare function tierMaxSkills(tier: string, maxConcurrent: number): number;
+export declare function tierEffectiveEpsilon(tier: string, epsilon: number): number;
+export declare function selectSkills(skills: SkillState[], n: number, tier: string, epsilon: number): {
+    selected: string[];
+    meta: SelectionMeta[];
+};

package/dist/bandit.js

@@ -0,0 +1,97 @@
+/**
+ * Epsilon-greedy bandit for skill selection.
+ * Ported from automaton.py — select_skills, _avg_reward, tier_max_skills, tier_effective_epsilon.
+ */
+function avgReward(skill) {
+    if (skill.timesSelected === 0)
+        return Infinity;
+    return skill.totalPnl / skill.timesSelected;
+}
+export function tierMaxSkills(tier, maxConcurrent) {
+    if (tier === "thriving" || tier === "normal")
+        return maxConcurrent;
+    if (tier === "conserving" || tier === "critical")
+        return 1;
+    return 0; // dead
+}
+export function tierEffectiveEpsilon(tier, epsilon) {
+    if (tier === "thriving" || tier === "normal")
+        return epsilon;
+    if (tier === "conserving")
+        return epsilon * 0.5;
+    return 0.0; // critical, dead — pure exploit or no runs
+}
+export function selectSkills(skills, n, tier, epsilon) {
+    const enabled = skills.filter((s) => s.enabled);
+    if (enabled.length === 0)
+        return { selected: [], meta: [] };
+    const effectiveEpsilon = tierEffectiveEpsilon(tier, epsilon);
+    const count = Math.min(n, enabled.length);
+    // Unplayed skills get priority
+    const unplayed = enabled.filter((s) => s.timesSelected === 0);
+    if (unplayed.length > 0) {
+        const shuffled = [...unplayed].sort(() => Math.random() - 0.5);
+        const picks = shuffled.slice(0, count);
+        const meta = picks.map((s) => ({
+            slug: s.slug,
+            reason: "unplayed",
+            score: null,
+        }));
+        if (picks.length < count) {
+            const remaining = enabled.filter((s) => !picks.includes(s));
+            const extra = remaining
+                .sort(() => Math.random() - 0.5)
+                .slice(0, count - picks.length);
+            picks.push(...extra);
+            meta.push(...extra.map((s) => ({
+                slug: s.slug,
+                reason: "backfill",
+                score: Math.round(avgReward(s) * 10000) / 10000,
+            })));
+        }
+        return {
+            selected: picks.map((s) => s.slug),
+            meta,
+        };
+    }
+    // Critical tier: always pick best
+    if (tier === "critical") {
+        const ranked = [...enabled].sort((a, b) => avgReward(b) - avgReward(a));
+        const picks = ranked.slice(0, count);
+        return {
+            selected: picks.map((s) => s.slug),
+            meta: picks.map((s) => ({
+                slug: s.slug,
+                reason: "critical_exploit",
+                score: Math.round(avgReward(s) * 10000) / 10000,
+            })),
+        };
+    }
+    // Epsilon-greedy
+    const selected = [];
+    const meta = [];
+    const available = [...enabled];
+    for (let i = 0; i < count && available.length > 0; i++) {
+        let pick;
+        let reason;
+        if (Math.random() < effectiveEpsilon) {
+            // Explore: random
+            const idx = Math.floor(Math.random() * available.length);
+            pick = available[idx];
+            reason = `explore (ε=${effectiveEpsilon.toFixed(2)})`;
+        }
+        else {
+            // Exploit: best avg reward
+            pick = available.reduce((best, s) => avgReward(s) > avgReward(best) ? s : best);
+            reason = "exploit";
+        }
+        selected.push(pick);
+        meta.push({
+            slug: pick.slug,
+            reason,
+            score: Math.round(avgReward(pick) * 10000) / 10000,
+        });
+        available.splice(available.indexOf(pick), 1);
+    }
+    return { selected: selected.map((s) => s.slug), meta };
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Simmer Automaton — OpenClaw Plugin
+ *
+ * Budget-enforced skill orchestration with survival tiers.
+ * Algorithm decides skill selection (bandit), budget, circuit breakers.
+ * LLM decides market-level trades within selected skills.
+ * API enforces hard spending limits on every trade.
+ */
+interface PluginApi {
+    pluginConfig?: Record<string, unknown>;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+    on: (hook: string, handler: (...args: unknown[]) => unknown) => void;
+    registerService: (service: {
+        id: string;
+        start: (ctx: ServiceCtx) => Promise<void>;
+        stop?: (ctx: ServiceCtx) => Promise<void>;
+    }) => void;
+    registerCommand: (cmd: {
+        name: string;
+        description: string;
+        acceptsArgs?: boolean;
+        handler: (ctx: CommandCtx) => Promise<{
+            text: string;
+        }>;
+    }) => void;
+}
+interface ServiceCtx {
+    stateDir: string;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+interface CommandCtx {
+    args?: string;
+}
+export default function register(pluginApi: PluginApi): void;
+export {};

package/dist/index.js

@@ -0,0 +1,218 @@
+/**
+ * Simmer Automaton — OpenClaw Plugin
+ *
+ * Budget-enforced skill orchestration with survival tiers.
+ * Algorithm decides skill selection (bandit), budget, circuit breakers.
+ * LLM decides market-level trades within selected skills.
+ * API enforces hard spending limits on every trade.
+ */
+import { SimmerApi } from "./api.js";
+import { selectSkills, tierMaxSkills } from "./bandit.js";
+import { computeTier } from "./tiers.js";
+import { generateTuningHints } from "./tuning.js";
+// Plugin-local state (in-memory, refreshed from API each cycle)
+let api;
+let cachedState = null;
+let cachedSkills = [];
+let banditState = [];
+let currentTier = "normal";
+let cycleCount = 0;
+let serviceRunning = false;
+let cycleTimer = null;
+// Config defaults
+let config = {
+    apiKey: "",
+    apiUrl: "https://api.simmer.markets",
+    cycleIntervalMs: 300_000,
+    epsilon: 0.2,
+    epsilonDecay: 0.995,
+    minEpsilon: 0.05,
+    maxConcurrent: 2,
+    venue: "simmer",
+};
+function loadConfig(pluginConfig) {
+    if (!pluginConfig)
+        return;
+    if (pluginConfig.apiKey)
+        config.apiKey = pluginConfig.apiKey;
+    if (pluginConfig.apiUrl)
+        config.apiUrl = pluginConfig.apiUrl;
+    if (pluginConfig.cycleIntervalMs)
+        config.cycleIntervalMs = pluginConfig.cycleIntervalMs;
+    if (pluginConfig.epsilon)
+        config.epsilon = pluginConfig.epsilon;
+    if (pluginConfig.epsilonDecay)
+        config.epsilonDecay = pluginConfig.epsilonDecay;
+    if (pluginConfig.minEpsilon)
+        config.minEpsilon = pluginConfig.minEpsilon;
+    if (pluginConfig.maxConcurrent)
+        config.maxConcurrent = pluginConfig.maxConcurrent;
+    if (pluginConfig.venue)
+        config.venue = pluginConfig.venue;
+}
+async function refreshState(logger) {
+    try {
+        cachedState = await api.getAutomatonState();
+        const skillsRes = await api.getSkills();
+        cachedSkills = skillsRes.skills;
+        if (cachedState.initialized) {
+            // Compute tier (totalPnl = 0 for now, will be enriched when P&L tracking is added)
+            currentTier = computeTier(cachedState, 0);
+        }
+    }
+    catch (e) {
+        logger.error(`[simmer] Failed to refresh state: ${e}`);
+    }
+}
+function buildPromptContext() {
+    if (!cachedState || !cachedState.initialized) {
+        return "[Simmer Automaton] Not initialized. Run: POST /api/sdk/automaton/init";
+    }
+    const lines = [
+        "## Simmer Automaton — Survival Context (read-only)",
+        "",
+        `**Tier:** ${currentTier} | **Venue:** ${config.venue}`,
+        `**Budget:** $${cachedState.budget_usd.toFixed(2)} | **Spent:** $${cachedState.spent_usd.toFixed(2)} | **Remaining:** $${cachedState.remaining_usd.toFixed(2)}`,
+        `**Halted:** ${cachedState.halted ? "YES — all trades blocked" : "no"}`,
+        `**Horizon:** ${cachedState.horizon_days} days`,
+        "",
+    ];
+    // Skill picks from bandit (if any)
+    if (banditState.length > 0) {
+        const n = tierMaxSkills(currentTier, config.maxConcurrent);
+        const { selected, meta } = selectSkills(banditState, n, currentTier, config.epsilon);
+        if (selected.length > 0) {
+            lines.push("**Selected skills this cycle:**");
+            for (const m of meta) {
+                lines.push(`- ${m.slug} (${m.reason}${m.score !== null ? `, score=${m.score}` : ""})`);
+            }
+            lines.push("");
+        }
+    }
+    // Tuning hints
+    const hints = generateTuningHints(banditState, cachedState.budget_usd);
+    if (hints.length > 0) {
+        lines.push("**Tuning hints:**");
+        for (const h of hints) {
+            lines.push(`- [${h.skill}] ${h.issue}: ${h.suggestion}`);
+        }
+        lines.push("");
+    }
+    if (currentTier === "critical") {
+        lines.push("**WARNING:** Critical tier — only exploiting best skill, no exploration.");
+    }
+    else if (currentTier === "dead") {
+        lines.push("**DEAD:** Budget exhausted or horizon expired. No skills will run.");
+    }
+    return lines.join("\n");
+}
+function formatStatus() {
+    if (!cachedState || !cachedState.initialized) {
+        return "Automaton not initialized. Use POST /api/sdk/automaton/init to start.";
+    }
+    const lines = [
+        `Tier: ${currentTier}`,
+        `Venue: ${config.venue}`,
+        `Budget: $${cachedState.budget_usd.toFixed(2)}`,
+        `Spent: $${cachedState.spent_usd.toFixed(2)}`,
+        `Remaining: $${cachedState.remaining_usd.toFixed(2)}`,
+        `Halted: ${cachedState.halted ? "YES" : "no"}`,
+        `Horizon: ${cachedState.horizon_days} days`,
+        `Cycles: ${cycleCount}`,
+        `Skills available: ${cachedSkills.length}`,
+    ];
+    return lines.join("\n");
+}
+// =============================================================================
+// Plugin registration
+// =============================================================================
+export default function register(pluginApi) {
+    loadConfig(pluginApi.pluginConfig);
+    if (!config.apiKey) {
+        pluginApi.logger.error("[simmer] No apiKey configured — plugin disabled");
+        return;
+    }
+    api = new SimmerApi(config.apiKey, config.apiUrl);
+    const logger = pluginApi.logger;
+    // --- Hook: before_prompt_build ---
+    // Inject survival context into every LLM prompt
+    pluginApi.on("before_prompt_build", async () => {
+        if (!cachedState) {
+            await refreshState(logger);
+        }
+        return { prependContext: buildPromptContext() };
+    });
+    // --- Service: background bandit cycle ---
+    pluginApi.registerService({
+        id: "simmer-automaton",
+        start: async (ctx) => {
+            ctx.logger.info("[simmer] Automaton service starting");
+            serviceRunning = true;
+            // Initial state fetch
+            await refreshState(ctx.logger);
+            // Periodic refresh
+            cycleTimer = setInterval(async () => {
+                if (!serviceRunning)
+                    return;
+                cycleCount++;
+                await refreshState(ctx.logger);
+                // Decay epsilon
+                config.epsilon = Math.max(config.minEpsilon, config.epsilon * config.epsilonDecay);
+                ctx.logger.info(`[simmer] Cycle ${cycleCount} | tier=${currentTier} | ε=${config.epsilon.toFixed(3)} | skills=${cachedSkills.length}`);
+            }, config.cycleIntervalMs);
+        },
+        stop: async (ctx) => {
+            ctx.logger.info("[simmer] Automaton service stopping");
+            serviceRunning = false;
+            if (cycleTimer) {
+                clearInterval(cycleTimer);
+                cycleTimer = null;
+            }
+        },
+    });
+    // --- Commands ---
+    pluginApi.registerCommand({
+        name: "simmer",
+        description: "Show Simmer automaton status",
+        acceptsArgs: true,
+        handler: async (ctx) => {
+            const subcommand = ctx.args?.trim().split(/\s+/)[0] || "status";
+            if (subcommand === "status") {
+                await refreshState(logger);
+                return { text: formatStatus() };
+            }
+            if (subcommand === "halt") {
+                try {
+                    await api.halt();
+                    await refreshState(logger);
+                    return { text: "Automaton halted. All trades will be rejected." };
+                }
+                catch (e) {
+                    return { text: `Failed to halt: ${e}` };
+                }
+            }
+            if (subcommand === "resume") {
+                try {
+                    await api.resume();
+                    await refreshState(logger);
+                    return { text: "Automaton resumed. Trading is active." };
+                }
+                catch (e) {
+                    return { text: `Failed to resume: ${e}` };
+                }
+            }
+            if (subcommand === "skills") {
+                await refreshState(logger);
+                if (cachedSkills.length === 0) {
+                    return { text: "No skills in registry." };
+                }
+                const lines = cachedSkills.map((s) => `- ${s.name} (${s.id}) — ${s.category}, ${s.difficulty}`);
+                return { text: `Skills (${cachedSkills.length}):\n${lines.join("\n")}` };
+            }
+            return {
+                text: "Usage: /simmer [status|halt|resume|skills]",
+            };
+        },
+    });
+    logger.info("[simmer] Plugin registered");
+}

package/dist/tiers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Survival tier computation.
+ * Ported from automaton.py — compute_tier.
+ */
+import type { AutomatonState } from "./api.js";
+export type Tier = "thriving" | "normal" | "conserving" | "critical" | "dead";
+export declare function computeTier(state: AutomatonState, totalPnl: number): Tier;

package/dist/tiers.js

@@ -0,0 +1,20 @@
+/**
+ * Survival tier computation.
+ * Ported from automaton.py — compute_tier.
+ */
+export function computeTier(state, totalPnl) {
+    if (state.budget_usd <= 0)
+        return "dead";
+    const budgetRemainingPct = (state.budget_usd - state.spent_usd + totalPnl) / state.budget_usd;
+    const startedAt = state.started_at ? new Date(state.started_at) : new Date();
+    const daysElapsed = (Date.now() - startedAt.getTime()) / (1000 * 60 * 60 * 24);
+    if (budgetRemainingPct <= 0 || daysElapsed >= state.horizon_days)
+        return "dead";
+    if (budgetRemainingPct < 0.1)
+        return "critical";
+    if (budgetRemainingPct < 0.3)
+        return "conserving";
+    if (totalPnl > 0 && budgetRemainingPct > 0.7)
+        return "thriving";
+    return "normal";
+}

package/dist/tuning.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tuning hints for the Clawbot LLM.
+ * Ported from automaton.py — generate_tuning_hints.
+ */
+import type { SkillState } from "./bandit.js";
+export interface TuningHint {
+    skill: string;
+    issue: string;
+    suggestion: string;
+    [key: string]: unknown;
+}
+export declare function generateTuningHints(skills: SkillState[], budgetUsd: number): TuningHint[];

package/dist/tuning.js

@@ -0,0 +1,68 @@
+/**
+ * Tuning hints for the Clawbot LLM.
+ * Ported from automaton.py — generate_tuning_hints.
+ */
+export function generateTuningHints(skills, budgetUsd) {
+    const hints = [];
+    for (const sk of skills) {
+        if (!sk.enabled || sk.timesSelected === 0)
+            continue;
+        // 1. Zero signals streak
+        if (sk.consecutiveZeroSignals >= 5) {
+            hints.push({
+                skill: sk.slug,
+                issue: "zero_signals_streak",
+                cycles: sk.consecutiveZeroSignals,
+                suggestion: `0 signals for ${sk.consecutiveZeroSignals} cycles — loosen thresholds or widen time windows`,
+            });
+        }
+        // 2. Concentrated loss
+        if (sk.totalPnl < 0 && budgetUsd > 0) {
+            const lossPct = (Math.abs(sk.totalPnl) / budgetUsd) * 100;
+            if (lossPct > 20) {
+                hints.push({
+                    skill: sk.slug,
+                    issue: "concentrated_loss",
+                    pnl: Math.round(sk.totalPnl * 100) / 100,
+                    pct_of_budget: Math.round(lossPct * 10) / 10,
+                    suggestion: `Lost $${Math.abs(sk.totalPnl).toFixed(2)} (${lossPct.toFixed(0)}% of budget) — consider disabling or reducing max bet`,
+                });
+            }
+        }
+        // 3. Inert — finds signals but never executes
+        if (sk.signalsFoundTotal > 50 && sk.tradesExecutedTotal === 0) {
+            hints.push({
+                skill: sk.slug,
+                issue: "inert",
+                signals: sk.signalsFoundTotal,
+                suggestion: `${sk.signalsFoundTotal} signals found, 0 executed — execution thresholds likely too tight`,
+            });
+        }
+        // 4. Win rate collapse
+        if (sk.timesSelected >= 10) {
+            const winRate = sk.timesRewarded / sk.timesSelected;
+            if (winRate < 0.2) {
+                hints.push({
+                    skill: sk.slug,
+                    issue: "win_rate_collapse",
+                    win_rate: Math.round(winRate * 1000) / 10,
+                    runs: sk.timesSelected,
+                    suggestion: `Win rate ${(winRate * 100).toFixed(0)}% over ${sk.timesSelected} cycles — strategy may not suit current markets`,
+                });
+            }
+        }
+        // 5. Safeguard dominant
+        const skipCounts = sk.lastCycle?.skipCounts || {};
+        const totalSkips = Object.values(skipCounts).reduce((a, b) => a + b, 0);
+        const safeguardSkips = skipCounts["safeguard"] || 0;
+        if (totalSkips >= 3 && safeguardSkips / totalSkips > 0.8) {
+            hints.push({
+                skill: sk.slug,
+                issue: "safeguard_dominant",
+                safeguard_pct: Math.round((safeguardSkips / totalSkips) * 100),
+                suggestion: "Most skips are safeguard blocks — markets may be too volatile or near resolution",
+            });
+        }
+    }
+    return hints;
+}

package/openclaw.plugin.json

@@ -0,0 +1,71 @@
+{
+  "id": "simmer-automaton",
+  "name": "Simmer Automaton",
+  "description": "Budget-enforced skill orchestration with survival tiers and bandit selection",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Simmer API key (sk_live_...)"
+      },
+      "apiUrl": {
+        "type": "string",
+        "default": "https://api.simmer.markets"
+      },
+      "cycleIntervalMs": {
+        "type": "number",
+        "default": 300000,
+        "description": "Bandit cycle interval in milliseconds (default: 5 min)"
+      },
+      "epsilon": {
+        "type": "number",
+        "default": 0.2,
+        "description": "Exploration rate for epsilon-greedy bandit (0-1)"
+      },
+      "epsilonDecay": {
+        "type": "number",
+        "default": 0.995,
+        "description": "Epsilon decay per cycle"
+      },
+      "minEpsilon": {
+        "type": "number",
+        "default": 0.05,
+        "description": "Minimum exploration rate"
+      },
+      "maxConcurrent": {
+        "type": "number",
+        "default": 2,
+        "description": "Max skills to run per cycle"
+      },
+      "venue": {
+        "type": "string",
+        "default": "simmer",
+        "description": "Trading venue (simmer for paper, polymarket for live)"
+      }
+    },
+    "required": ["apiKey"]
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Simmer API Key",
+      "sensitive": true,
+      "placeholder": "sk_live_...",
+      "help": "Get from simmer.markets/dashboard"
+    },
+    "venue": {
+      "label": "Trading Venue",
+      "help": "Use 'simmer' for paper trading, 'polymarket' for live"
+    },
+    "epsilon": {
+      "label": "Exploration Rate",
+      "advanced": true
+    },
+    "cycleIntervalMs": {
+      "label": "Cycle Interval (ms)",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "simmer-automaton",
+  "version": "0.1.0",
+  "description": "Simmer Automaton plugin for OpenClaw — budget-enforced skill orchestration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["openclaw", "plugin", "simmer", "prediction-markets", "trading"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,77 @@
+/**
+ * Simmer API client for the automaton plugin.
+ * Thin wrapper around fetch — reads automaton state, skills registry.
+ */
+
+export interface AutomatonState {
+  initialized: boolean;
+  budget_usd: number;
+  spent_usd: number;
+  remaining_usd: number;
+  halted: boolean;
+  tier: string;
+  horizon_days: number;
+  started_at: string | null;
+}
+
+export interface Skill {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  tags: string[];
+  difficulty: string;
+  install: string;
+  clawhub_url: string;
+  requires: string[];
+  best_when: string | null;
+}
+
+export class SimmerApi {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(apiKey: string, baseUrl = "https://api.simmer.markets") {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  private async request<T>(path: string, opts?: RequestInit): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...opts,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...(opts?.headers || {}),
+      },
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Simmer API ${res.status}: ${body}`);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  async getAutomatonState(): Promise<AutomatonState> {
+    return this.request("/api/sdk/automaton/state");
+  }
+
+  async initAutomaton(budgetUsd: number, horizonDays = 30) {
+    return this.request("/api/sdk/automaton/init", {
+      method: "POST",
+      body: JSON.stringify({ budget_usd: budgetUsd, horizon_days: horizonDays }),
+    });
+  }
+
+  async halt() {
+    return this.request("/api/sdk/automaton/halt", { method: "POST" });
+  }
+
+  async resume() {
+    return this.request("/api/sdk/automaton/resume", { method: "POST" });
+  }
+
+  async getSkills(): Promise<{ skills: Skill[]; total: number }> {
+    return this.request("/api/sdk/skills");
+  }
+}

package/src/bandit.ts

@@ -0,0 +1,135 @@
+/**
+ * Epsilon-greedy bandit for skill selection.
+ * Ported from automaton.py — select_skills, _avg_reward, tier_max_skills, tier_effective_epsilon.
+ */
+
+export interface SkillState {
+  slug: string;
+  enabled: boolean;
+  timesSelected: number;
+  timesRewarded: number;
+  totalPnl: number;
+  consecutiveZeroSignals: number;
+  signalsFoundTotal: number;
+  tradesExecutedTotal: number;
+  lastCycle?: {
+    skipCounts?: Record<string, number>;
+  };
+}
+
+export interface SelectionMeta {
+  slug: string;
+  reason: string;
+  score: number | null;
+}
+
+function avgReward(skill: SkillState): number {
+  if (skill.timesSelected === 0) return Infinity;
+  return skill.totalPnl / skill.timesSelected;
+}
+
+export function tierMaxSkills(tier: string, maxConcurrent: number): number {
+  if (tier === "thriving" || tier === "normal") return maxConcurrent;
+  if (tier === "conserving" || tier === "critical") return 1;
+  return 0; // dead
+}
+
+export function tierEffectiveEpsilon(tier: string, epsilon: number): number {
+  if (tier === "thriving" || tier === "normal") return epsilon;
+  if (tier === "conserving") return epsilon * 0.5;
+  return 0.0; // critical, dead — pure exploit or no runs
+}
+
+export function selectSkills(
+  skills: SkillState[],
+  n: number,
+  tier: string,
+  epsilon: number,
+): { selected: string[]; meta: SelectionMeta[] } {
+  const enabled = skills.filter((s) => s.enabled);
+  if (enabled.length === 0) return { selected: [], meta: [] };
+
+  const effectiveEpsilon = tierEffectiveEpsilon(tier, epsilon);
+  const count = Math.min(n, enabled.length);
+
+  // Unplayed skills get priority
+  const unplayed = enabled.filter((s) => s.timesSelected === 0);
+  if (unplayed.length > 0) {
+    const shuffled = [...unplayed].sort(() => Math.random() - 0.5);
+    const picks = shuffled.slice(0, count);
+    const meta: SelectionMeta[] = picks.map((s) => ({
+      slug: s.slug,
+      reason: "unplayed",
+      score: null,
+    }));
+
+    if (picks.length < count) {
+      const remaining = enabled.filter((s) => !picks.includes(s));
+      const extra = remaining
+        .sort(() => Math.random() - 0.5)
+        .slice(0, count - picks.length);
+      picks.push(...extra);
+      meta.push(
+        ...extra.map((s) => ({
+          slug: s.slug,
+          reason: "backfill",
+          score: Math.round(avgReward(s) * 10000) / 10000,
+        })),
+      );
+    }
+
+    return {
+      selected: picks.map((s) => s.slug),
+      meta,
+    };
+  }
+
+  // Critical tier: always pick best
+  if (tier === "critical") {
+    const ranked = [...enabled].sort(
+      (a, b) => avgReward(b) - avgReward(a),
+    );
+    const picks = ranked.slice(0, count);
+    return {
+      selected: picks.map((s) => s.slug),
+      meta: picks.map((s) => ({
+        slug: s.slug,
+        reason: "critical_exploit",
+        score: Math.round(avgReward(s) * 10000) / 10000,
+      })),
+    };
+  }
+
+  // Epsilon-greedy
+  const selected: SkillState[] = [];
+  const meta: SelectionMeta[] = [];
+  const available = [...enabled];
+
+  for (let i = 0; i < count && available.length > 0; i++) {
+    let pick: SkillState;
+    let reason: string;
+
+    if (Math.random() < effectiveEpsilon) {
+      // Explore: random
+      const idx = Math.floor(Math.random() * available.length);
+      pick = available[idx];
+      reason = `explore (ε=${effectiveEpsilon.toFixed(2)})`;
+    } else {
+      // Exploit: best avg reward
+      pick = available.reduce((best, s) =>
+        avgReward(s) > avgReward(best) ? s : best,
+      );
+      reason = "exploit";
+    }
+
+    selected.push(pick);
+    meta.push({
+      slug: pick.slug,
+      reason,
+      score: Math.round(avgReward(pick) * 10000) / 10000,
+    });
+    available.splice(available.indexOf(pick), 1);
+  }
+
+  return { selected: selected.map((s) => s.slug), meta };
+}

package/src/index.ts

@@ -0,0 +1,262 @@
+/**
+ * Simmer Automaton — OpenClaw Plugin
+ *
+ * Budget-enforced skill orchestration with survival tiers.
+ * Algorithm decides skill selection (bandit), budget, circuit breakers.
+ * LLM decides market-level trades within selected skills.
+ * API enforces hard spending limits on every trade.
+ */
+
+import { SimmerApi } from "./api.js";
+import type { AutomatonState, Skill } from "./api.js";
+import { selectSkills, tierMaxSkills, type SkillState } from "./bandit.js";
+import { computeTier, type Tier } from "./tiers.js";
+import { generateTuningHints } from "./tuning.js";
+
+// OpenClaw types — we declare minimal interfaces to avoid requiring the SDK as a dependency
+interface PluginApi {
+  pluginConfig?: Record<string, unknown>;
+  logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+  on: (hook: string, handler: (...args: unknown[]) => unknown) => void;
+  registerService: (service: { id: string; start: (ctx: ServiceCtx) => Promise<void>; stop?: (ctx: ServiceCtx) => Promise<void> }) => void;
+  registerCommand: (cmd: { name: string; description: string; acceptsArgs?: boolean; handler: (ctx: CommandCtx) => Promise<{ text: string }> }) => void;
+}
+
+interface ServiceCtx {
+  stateDir: string;
+  logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+interface CommandCtx {
+  args?: string;
+}
+
+// Plugin-local state (in-memory, refreshed from API each cycle)
+let api: SimmerApi;
+let cachedState: AutomatonState | null = null;
+let cachedSkills: Skill[] = [];
+let banditState: SkillState[] = [];
+let currentTier: Tier = "normal";
+let cycleCount = 0;
+let serviceRunning = false;
+let cycleTimer: ReturnType<typeof setInterval> | null = null;
+
+// Config defaults
+let config = {
+  apiKey: "",
+  apiUrl: "https://api.simmer.markets",
+  cycleIntervalMs: 300_000,
+  epsilon: 0.2,
+  epsilonDecay: 0.995,
+  minEpsilon: 0.05,
+  maxConcurrent: 2,
+  venue: "simmer",
+};
+
+function loadConfig(pluginConfig?: Record<string, unknown>) {
+  if (!pluginConfig) return;
+  if (pluginConfig.apiKey) config.apiKey = pluginConfig.apiKey as string;
+  if (pluginConfig.apiUrl) config.apiUrl = pluginConfig.apiUrl as string;
+  if (pluginConfig.cycleIntervalMs) config.cycleIntervalMs = pluginConfig.cycleIntervalMs as number;
+  if (pluginConfig.epsilon) config.epsilon = pluginConfig.epsilon as number;
+  if (pluginConfig.epsilonDecay) config.epsilonDecay = pluginConfig.epsilonDecay as number;
+  if (pluginConfig.minEpsilon) config.minEpsilon = pluginConfig.minEpsilon as number;
+  if (pluginConfig.maxConcurrent) config.maxConcurrent = pluginConfig.maxConcurrent as number;
+  if (pluginConfig.venue) config.venue = pluginConfig.venue as string;
+}
+
+async function refreshState(logger: { info: (m: string) => void; error: (m: string) => void }) {
+  try {
+    cachedState = await api.getAutomatonState();
+    const skillsRes = await api.getSkills();
+    cachedSkills = skillsRes.skills;
+
+    if (cachedState.initialized) {
+      // Compute tier (totalPnl = 0 for now, will be enriched when P&L tracking is added)
+      currentTier = computeTier(cachedState, 0);
+    }
+  } catch (e) {
+    logger.error(`[simmer] Failed to refresh state: ${e}`);
+  }
+}
+
+function buildPromptContext(): string {
+  if (!cachedState || !cachedState.initialized) {
+    return "[Simmer Automaton] Not initialized. Run: POST /api/sdk/automaton/init";
+  }
+
+  const lines = [
+    "## Simmer Automaton — Survival Context (read-only)",
+    "",
+    `**Tier:** ${currentTier} | **Venue:** ${config.venue}`,
+    `**Budget:** $${cachedState.budget_usd.toFixed(2)} | **Spent:** $${cachedState.spent_usd.toFixed(2)} | **Remaining:** $${cachedState.remaining_usd.toFixed(2)}`,
+    `**Halted:** ${cachedState.halted ? "YES — all trades blocked" : "no"}`,
+    `**Horizon:** ${cachedState.horizon_days} days`,
+    "",
+  ];
+
+  // Skill picks from bandit (if any)
+  if (banditState.length > 0) {
+    const n = tierMaxSkills(currentTier, config.maxConcurrent);
+    const { selected, meta } = selectSkills(banditState, n, currentTier, config.epsilon);
+    if (selected.length > 0) {
+      lines.push("**Selected skills this cycle:**");
+      for (const m of meta) {
+        lines.push(`- ${m.slug} (${m.reason}${m.score !== null ? `, score=${m.score}` : ""})`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Tuning hints
+  const hints = generateTuningHints(banditState, cachedState.budget_usd);
+  if (hints.length > 0) {
+    lines.push("**Tuning hints:**");
+    for (const h of hints) {
+      lines.push(`- [${h.skill}] ${h.issue}: ${h.suggestion}`);
+    }
+    lines.push("");
+  }
+
+  if (currentTier === "critical") {
+    lines.push("**WARNING:** Critical tier — only exploiting best skill, no exploration.");
+  } else if (currentTier === "dead") {
+    lines.push("**DEAD:** Budget exhausted or horizon expired. No skills will run.");
+  }
+
+  return lines.join("\n");
+}
+
+function formatStatus(): string {
+  if (!cachedState || !cachedState.initialized) {
+    return "Automaton not initialized. Use POST /api/sdk/automaton/init to start.";
+  }
+
+  const lines = [
+    `Tier: ${currentTier}`,
+    `Venue: ${config.venue}`,
+    `Budget: $${cachedState.budget_usd.toFixed(2)}`,
+    `Spent: $${cachedState.spent_usd.toFixed(2)}`,
+    `Remaining: $${cachedState.remaining_usd.toFixed(2)}`,
+    `Halted: ${cachedState.halted ? "YES" : "no"}`,
+    `Horizon: ${cachedState.horizon_days} days`,
+    `Cycles: ${cycleCount}`,
+    `Skills available: ${cachedSkills.length}`,
+  ];
+  return lines.join("\n");
+}
+
+// =============================================================================
+// Plugin registration
+// =============================================================================
+
+export default function register(pluginApi: PluginApi) {
+  loadConfig(pluginApi.pluginConfig);
+
+  if (!config.apiKey) {
+    pluginApi.logger.error("[simmer] No apiKey configured — plugin disabled");
+    return;
+  }
+
+  api = new SimmerApi(config.apiKey, config.apiUrl);
+  const logger = pluginApi.logger;
+
+  // --- Hook: before_prompt_build ---
+  // Inject survival context into every LLM prompt
+  pluginApi.on("before_prompt_build", async () => {
+    if (!cachedState) {
+      await refreshState(logger);
+    }
+    return { prependContext: buildPromptContext() };
+  });
+
+  // --- Service: background bandit cycle ---
+  pluginApi.registerService({
+    id: "simmer-automaton",
+    start: async (ctx: ServiceCtx) => {
+      ctx.logger.info("[simmer] Automaton service starting");
+      serviceRunning = true;
+
+      // Initial state fetch
+      await refreshState(ctx.logger);
+
+      // Periodic refresh
+      cycleTimer = setInterval(async () => {
+        if (!serviceRunning) return;
+        cycleCount++;
+        await refreshState(ctx.logger);
+
+        // Decay epsilon
+        config.epsilon = Math.max(
+          config.minEpsilon,
+          config.epsilon * config.epsilonDecay,
+        );
+
+        ctx.logger.info(
+          `[simmer] Cycle ${cycleCount} | tier=${currentTier} | ε=${config.epsilon.toFixed(3)} | skills=${cachedSkills.length}`,
+        );
+      }, config.cycleIntervalMs);
+    },
+    stop: async (ctx: ServiceCtx) => {
+      ctx.logger.info("[simmer] Automaton service stopping");
+      serviceRunning = false;
+      if (cycleTimer) {
+        clearInterval(cycleTimer);
+        cycleTimer = null;
+      }
+    },
+  });
+
+  // --- Commands ---
+
+  pluginApi.registerCommand({
+    name: "simmer",
+    description: "Show Simmer automaton status",
+    acceptsArgs: true,
+    handler: async (ctx: CommandCtx) => {
+      const subcommand = ctx.args?.trim().split(/\s+/)[0] || "status";
+
+      if (subcommand === "status") {
+        await refreshState(logger);
+        return { text: formatStatus() };
+      }
+
+      if (subcommand === "halt") {
+        try {
+          await api.halt();
+          await refreshState(logger);
+          return { text: "Automaton halted. All trades will be rejected." };
+        } catch (e) {
+          return { text: `Failed to halt: ${e}` };
+        }
+      }
+
+      if (subcommand === "resume") {
+        try {
+          await api.resume();
+          await refreshState(logger);
+          return { text: "Automaton resumed. Trading is active." };
+        } catch (e) {
+          return { text: `Failed to resume: ${e}` };
+        }
+      }
+
+      if (subcommand === "skills") {
+        await refreshState(logger);
+        if (cachedSkills.length === 0) {
+          return { text: "No skills in registry." };
+        }
+        const lines = cachedSkills.map(
+          (s) => `- ${s.name} (${s.id}) — ${s.category}, ${s.difficulty}`,
+        );
+        return { text: `Skills (${cachedSkills.length}):\n${lines.join("\n")}` };
+      }
+
+      return {
+        text: "Usage: /simmer [status|halt|resume|skills]",
+      };
+    },
+  });
+
+  logger.info("[simmer] Plugin registered");
+}

package/src/tiers.ts

@@ -0,0 +1,25 @@
+/**
+ * Survival tier computation.
+ * Ported from automaton.py — compute_tier.
+ */
+
+import type { AutomatonState } from "./api.js";
+
+export type Tier = "thriving" | "normal" | "conserving" | "critical" | "dead";
+
+export function computeTier(state: AutomatonState, totalPnl: number): Tier {
+  if (state.budget_usd <= 0) return "dead";
+
+  const budgetRemainingPct =
+    (state.budget_usd - state.spent_usd + totalPnl) / state.budget_usd;
+
+  const startedAt = state.started_at ? new Date(state.started_at) : new Date();
+  const daysElapsed =
+    (Date.now() - startedAt.getTime()) / (1000 * 60 * 60 * 24);
+
+  if (budgetRemainingPct <= 0 || daysElapsed >= state.horizon_days) return "dead";
+  if (budgetRemainingPct < 0.1) return "critical";
+  if (budgetRemainingPct < 0.3) return "conserving";
+  if (totalPnl > 0 && budgetRemainingPct > 0.7) return "thriving";
+  return "normal";
+}

package/src/tuning.ts

@@ -0,0 +1,91 @@
+/**
+ * Tuning hints for the Clawbot LLM.
+ * Ported from automaton.py — generate_tuning_hints.
+ */
+
+import type { SkillState } from "./bandit.js";
+
+export interface TuningHint {
+  skill: string;
+  issue: string;
+  suggestion: string;
+  [key: string]: unknown;
+}
+
+export function generateTuningHints(
+  skills: SkillState[],
+  budgetUsd: number,
+): TuningHint[] {
+  const hints: TuningHint[] = [];
+
+  for (const sk of skills) {
+    if (!sk.enabled || sk.timesSelected === 0) continue;
+
+    // 1. Zero signals streak
+    if (sk.consecutiveZeroSignals >= 5) {
+      hints.push({
+        skill: sk.slug,
+        issue: "zero_signals_streak",
+        cycles: sk.consecutiveZeroSignals,
+        suggestion: `0 signals for ${sk.consecutiveZeroSignals} cycles — loosen thresholds or widen time windows`,
+      });
+    }
+
+    // 2. Concentrated loss
+    if (sk.totalPnl < 0 && budgetUsd > 0) {
+      const lossPct = (Math.abs(sk.totalPnl) / budgetUsd) * 100;
+      if (lossPct > 20) {
+        hints.push({
+          skill: sk.slug,
+          issue: "concentrated_loss",
+          pnl: Math.round(sk.totalPnl * 100) / 100,
+          pct_of_budget: Math.round(lossPct * 10) / 10,
+          suggestion: `Lost $${Math.abs(sk.totalPnl).toFixed(2)} (${lossPct.toFixed(0)}% of budget) — consider disabling or reducing max bet`,
+        });
+      }
+    }
+
+    // 3. Inert — finds signals but never executes
+    if (sk.signalsFoundTotal > 50 && sk.tradesExecutedTotal === 0) {
+      hints.push({
+        skill: sk.slug,
+        issue: "inert",
+        signals: sk.signalsFoundTotal,
+        suggestion: `${sk.signalsFoundTotal} signals found, 0 executed — execution thresholds likely too tight`,
+      });
+    }
+
+    // 4. Win rate collapse
+    if (sk.timesSelected >= 10) {
+      const winRate = sk.timesRewarded / sk.timesSelected;
+      if (winRate < 0.2) {
+        hints.push({
+          skill: sk.slug,
+          issue: "win_rate_collapse",
+          win_rate: Math.round(winRate * 1000) / 10,
+          runs: sk.timesSelected,
+          suggestion: `Win rate ${(winRate * 100).toFixed(0)}% over ${sk.timesSelected} cycles — strategy may not suit current markets`,
+        });
+      }
+    }
+
+    // 5. Safeguard dominant
+    const skipCounts = sk.lastCycle?.skipCounts || {};
+    const totalSkips = Object.values(skipCounts).reduce(
+      (a, b) => a + b,
+      0,
+    );
+    const safeguardSkips = skipCounts["safeguard"] || 0;
+    if (totalSkips >= 3 && safeguardSkips / totalSkips > 0.8) {
+      hints.push({
+        skill: sk.slug,
+        issue: "safeguard_dominant",
+        safeguard_pct: Math.round((safeguardSkips / totalSkips) * 100),
+        suggestion:
+          "Most skips are safeguard blocks — markets may be too volatile or near resolution",
+      });
+    }
+  }
+
+  return hints;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}