@nvsudo/openclaw-skill 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# `@behavr/openclaw-skill`
+
+Thin, declarative Behavr client for OpenClaw/Moltbot-style agents.
+
+## Why this exists
+
+Agents increasingly need to:
+
+- scout a tone/config quickly
+- cache a recommended config
+- publish a community config
+- vote on config usefulness / ROI
+
+This package gives agent runtimes a safe client (JSON-only config flows, no arbitrary code execution).
+
+## Actions
+
+- `behavr.findConfig`
+- `behavr.fetchConfig`
+- `behavr.publishConfig`
+- `behavr.voteConfig`
+
+See `manifest.json` for the proposed action list.
+
+## Example
+
+```ts
+import { BehavrOpenClawSkillClient, MemoryConfigCache } from '@behavr/openclaw-skill';
+
+const client = new BehavrOpenClawSkillClient({
+  baseUrl: 'http://localhost:3000',
+  apiKey: process.env.BEHAVR_API_KEY
+});
+
+const cache = new MemoryConfigCache();
+
+const recommendation = await client.scoutWithCache({
+  cache,
+  input: {
+    segmentKey: 'sales.sdr_followup.email',
+    modelFamily: 'qwen',
+    topK: 3,
+    requireCertified: true
+  }
+});
+```
+
+## Notes
+
+- `fetchConfig()` currently resolves via `/api/v1/configs` list filtering because the hosted API does not yet expose a dedicated config-by-slug endpoint.
+- Hosted certification, ranking, and anti-gaming remain part of Behavr Cloud (private).
+

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { type BehavrConfigDoc } from '@behavr/config-spec';
+export interface OpenClawSkillConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface FindConfigInput {
+    segmentKey: string;
+    modelFamily?: string;
+    vertical?: string;
+    useCase?: string;
+    topK?: number;
+    maxCostUsdPer1kMessages?: number;
+    requireCertified?: boolean;
+}
+export interface PublishConfigInput {
+    doc: BehavrConfigDoc;
+}
+export interface VoteConfigInput {
+    configVersionId: string;
+    segmentKey: string;
+    modelFamily?: string;
+    helpful: boolean;
+    roiRating?: number;
+    comment?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ListConfigsInput {
+    segmentKey?: string;
+    modelFamily?: string;
+    vertical?: string;
+    useCase?: string;
+    limit?: number;
+}
+export interface FetchConfigInput {
+    slug: string;
+    version?: string;
+    segmentKey?: string;
+    modelFamily?: string;
+}
+export interface AgentCacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+export interface ConfigCache {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttlMs: number): void;
+    delete(key: string): void;
+}
+export declare class MemoryConfigCache implements ConfigCache {
+    private readonly store;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T, ttlMs: number): void;
+    delete(key: string): void;
+}
+export declare function buildScoutCacheKey(input: FindConfigInput): string;
+export declare function buildScenarioCacheKey(args: {
+    segmentKey: string;
+    modelFamily?: string;
+    scenarioKey?: string;
+}): string;
+export declare class BehavrOpenClawSkillClient {
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(config?: OpenClawSkillConfig);
+    findConfig<T = any>(input: FindConfigInput): Promise<T>;
+    listConfigs<T = any>(input?: ListConfigsInput): Promise<T>;
+    fetchConfig<T extends {
+        configs?: Array<{
+            slug?: string;
+            version?: string;
+        }>;
+    } = any>(input: FetchConfigInput): Promise<any | null>;
+    publishConfig<T = any>(input: PublishConfigInput): Promise<T>;
+    voteConfig<T = any>(input: VoteConfigInput): Promise<T>;
+    scoutWithCache<T = any>(args: {
+        input: FindConfigInput;
+        cache: ConfigCache;
+        ttlMs?: number;
+        cacheKey?: string;
+    }): Promise<T>;
+    private getJson;
+    private postJson;
+}
+export interface OpenClawActionHandlerContext {
+    client: BehavrOpenClawSkillClient;
+    cache?: ConfigCache;
+}
+export declare function createOpenClawActionHandlers(context: OpenClawActionHandlerContext): {
+    readonly 'behavr.findConfig': (input: FindConfigInput) => Promise<any>;
+    readonly 'behavr.fetchConfig': (input: FetchConfigInput) => Promise<any>;
+    readonly 'behavr.publishConfig': (input: PublishConfigInput) => Promise<any>;
+    readonly 'behavr.voteConfig': (input: VoteConfigInput) => Promise<any>;
+};

package/dist/index.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BehavrOpenClawSkillClient = exports.MemoryConfigCache = void 0;
+exports.buildScoutCacheKey = buildScoutCacheKey;
+exports.buildScenarioCacheKey = buildScenarioCacheKey;
+exports.createOpenClawActionHandlers = createOpenClawActionHandlers;
+const config_spec_1 = require("@behavr/config-spec");
+class MemoryConfigCache {
+    constructor() {
+        this.store = new Map();
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= Date.now()) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        this.store.set(key, { value, expiresAt: Date.now() + Math.max(0, ttlMs) });
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+}
+exports.MemoryConfigCache = MemoryConfigCache;
+function normalizeBaseUrl(baseUrl) {
+    return (baseUrl ?? 'https://api.behavr.dev').replace(/\/+$/, '');
+}
+function makeHeaders(apiKey, extra) {
+    return {
+        'Content-Type': 'application/json',
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...(extra ?? {}),
+    };
+}
+async function parseResponse(response) {
+    const text = await response.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = { raw: text };
+    }
+    if (!response.ok) {
+        const message = body?.message || body?.error || `HTTP ${response.status}`;
+        throw new Error(message);
+    }
+    return body;
+}
+function buildScoutCacheKey(input) {
+    return [
+        'behavr',
+        input.segmentKey,
+        input.modelFamily ?? '*',
+        input.vertical ?? '*',
+        input.useCase ?? '*',
+        String(input.requireCertified ?? true),
+        input.maxCostUsdPer1kMessages ?? '*',
+    ].join('|');
+}
+function buildScenarioCacheKey(args) {
+    return ['behavr-scout', args.segmentKey, args.modelFamily ?? '*', args.scenarioKey ?? '*'].join('|');
+}
+class BehavrOpenClawSkillClient {
+    constructor(config = {}) {
+        this.baseUrl = normalizeBaseUrl(config.baseUrl);
+        this.apiKey = config.apiKey;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+        if (!this.fetchImpl) {
+            throw new Error('BehavrOpenClawSkillClient: fetch implementation is required in this runtime');
+        }
+    }
+    async findConfig(input) {
+        return this.postJson('/api/v1/configs/recommend', {
+            segmentKey: input.segmentKey,
+            modelFamily: input.modelFamily,
+            vertical: input.vertical,
+            useCase: input.useCase,
+            topK: input.topK ?? 3,
+            maxCostUsdPer1kMessages: input.maxCostUsdPer1kMessages,
+            requireCertified: input.requireCertified ?? true,
+        });
+    }
+    async listConfigs(input = {}) {
+        const params = new URLSearchParams();
+        if (input.segmentKey)
+            params.set('segmentKey', input.segmentKey);
+        if (input.modelFamily)
+            params.set('modelFamily', input.modelFamily);
+        if (input.vertical)
+            params.set('vertical', input.vertical);
+        if (input.useCase)
+            params.set('useCase', input.useCase);
+        if (input.limit !== undefined)
+            params.set('limit', String(input.limit));
+        const suffix = params.size ? `?${params.toString()}` : '';
+        return this.getJson(`/api/v1/configs${suffix}`);
+    }
+    async fetchConfig(input) {
+        const result = await this.listConfigs({
+            segmentKey: input.segmentKey,
+            modelFamily: input.modelFamily,
+            limit: 100,
+        });
+        const configs = Array.isArray(result?.configs) ? result.configs : [];
+        return (configs.find((cfg) => cfg.slug === input.slug && (input.version ? cfg.version === input.version : true)) ??
+            null);
+    }
+    async publishConfig(input) {
+        const validation = (0, config_spec_1.validateBehavrConfigDoc)(input.doc);
+        if (!validation.ok) {
+            const message = validation.issues.map((i) => `${i.path}: ${i.message}`).join('; ');
+            throw new Error(`Invalid Behavr config document: ${message}`);
+        }
+        if (!this.apiKey) {
+            throw new Error('publishConfig requires apiKey');
+        }
+        return this.postJson('/api/v1/configs', (0, config_spec_1.toApiSharePayload)(input.doc), true);
+    }
+    async voteConfig(input) {
+        if (!this.apiKey) {
+            throw new Error('voteConfig requires apiKey');
+        }
+        return this.postJson('/api/v1/configs/vote', {
+            configVersionId: input.configVersionId,
+            segmentKey: input.segmentKey,
+            modelFamily: input.modelFamily,
+            helpful: input.helpful,
+            roiRating: input.roiRating,
+            comment: input.comment,
+            metadata: input.metadata ?? {},
+        }, true);
+    }
+    async scoutWithCache(args) {
+        const ttlMs = args.ttlMs ?? 5 * 60 * 1000;
+        const key = args.cacheKey ?? buildScoutCacheKey(args.input);
+        const cached = args.cache.get(key);
+        if (cached)
+            return cached;
+        const result = await this.findConfig(args.input);
+        args.cache.set(key, result, ttlMs);
+        return result;
+    }
+    async getJson(path) {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: makeHeaders(this.apiKey),
+        });
+        return parseResponse(response);
+    }
+    async postJson(path, body, requireApiKey = false) {
+        if (requireApiKey && !this.apiKey) {
+            throw new Error(`${path} requires apiKey`);
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: makeHeaders(this.apiKey),
+            body: JSON.stringify(body),
+        });
+        return parseResponse(response);
+    }
+}
+exports.BehavrOpenClawSkillClient = BehavrOpenClawSkillClient;
+function createOpenClawActionHandlers(context) {
+    return {
+        'behavr.findConfig': async (input) => {
+            if (context.cache) {
+                return context.client.scoutWithCache({ input, cache: context.cache });
+            }
+            return context.client.findConfig(input);
+        },
+        'behavr.fetchConfig': async (input) => context.client.fetchConfig(input),
+        'behavr.publishConfig': async (input) => context.client.publishConfig(input),
+        'behavr.voteConfig': async (input) => context.client.voteConfig(input),
+    };
+}

package/manifest.json

@@ -0,0 +1,32 @@
+{
+  "name": "behavr-openclaw-skill",
+  "version": "0.1.0",
+  "description": "Declarative Behavr config fetch/publish/vote client for OpenClaw/Moltbot-style agents",
+  "safety": {
+    "mode": "declarative-only",
+    "notes": [
+      "No arbitrary code execution",
+      "Config payloads are JSON documents",
+      "Hosted Behavr certification remains separate"
+    ]
+  },
+  "actions": [
+    {
+      "id": "behavr.findConfig",
+      "description": "Get ranked config recommendations for a segment/model context"
+    },
+    {
+      "id": "behavr.fetchConfig",
+      "description": "Fetch a config candidate by slug/version via marketplace list filtering"
+    },
+    {
+      "id": "behavr.publishConfig",
+      "description": "Publish a community config to Behavr marketplace"
+    },
+    {
+      "id": "behavr.voteConfig",
+      "description": "Submit verified helpful/ROI feedback for a config version"
+    }
+  ]
+}
+

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nvsudo/openclaw-skill",
+  "version": "0.1.0",
+  "description": "Thin client + action helpers for OpenClaw/Moltbot-style agents to fetch, publish, and vote on Behavr configs",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*",
+    "manifest.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit"
+  },
+  "keywords": [
+    "behavr",
+    "openclaw",
+    "moltbot",
+    "agent",
+    "config"
+  ],
+  "dependencies": {
+    "@behavr/config-spec": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nvsudo/behavr-oss.git"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}
+