@volisphere/commercial 0.1.0 → 0.2.1

package/dist/client.d.ts

@@ -63,14 +63,14 @@ export interface SkillConfig {
 }
 export interface CampaignParams {
     name: string;
+    billing: "cpi" | "cpr" | "cpa";
     daily_budget_micros: number;
     total_budget_micros: number;
-    bid_micros: number;
-    billing_model: "CPM" | "CPC" | "CPA";
-    categories: string[];
+    default_bid_micros: number;
+    start_at: string;
+    end_at?: string;
+    intent_categories: string[];
     scenes: string[];
-    start_date?: string;
-    end_date?: string;
 }
 export interface Campaign {
     id: string;
@@ -91,11 +91,40 @@ export interface Campaign {
     updated_at: string;
 }
 export interface AdEntitySchema {
-    title: string;
-    description: string;
-    call_to_action: string;
-    landing_url: string;
-    image_url?: string;
+    schema_version: string;
+    identity: {
+        name: string;
+        provider: string;
+        entity_type: string;
+    };
+    capability: {
+        format: string;
+        placement: string[];
+    };
+    specs: {
+        intent_categories: string[];
+        scenes: string[];
+        regions: string[];
+        budget_ranges: string[];
+    };
+    actions: Array<{
+        label: string;
+        endpoint: string;
+        type: string;
+    }>;
+    trust: {
+        verified: boolean;
+    };
+    ad_meta: {
+        billing: string;
+        bid_micros: number;
+    };
+    render: {
+        headline: string;
+        short_desc: string;
+        image_url?: string;
+        call_to_action: string;
+    };
 }
 export interface AdEntity {
     id: string;
@@ -135,6 +164,7 @@ export interface RegisterAgentResponse {
     };
     claim_token: string;
     claim_url: string;
+    api_key: string;
 }
 export interface AgentProfile {
     id: string;
@@ -144,11 +174,50 @@ export interface AgentProfile {
     is_online: boolean;
     monetization_enabled: boolean;
 }
+export interface InvokeAgentParams {
+    target_agent: string;
+    message: string;
+    skill?: string;
+}
+export interface InvokeAgentResponse {
+    request_id: string;
+    agent_slug: string;
+    agent_name: string;
+    response: string;
+    sponsored?: Array<{
+        ad_entity_id: string;
+        campaign_id: string;
+        title: string;
+        description: string;
+        call_to_action: string;
+        landing_url: string;
+        recommendation_id: string;
+    }>;
+}
+export interface DailyStatPoint {
+    date: string;
+    spend_micros: number;
+    earnings_micros: number;
+    match_count: number;
+    impression_count: number;
+    action_count: number;
+}
+export interface StatsResponse {
+    period: string;
+    points: DailyStatPoint[];
+    total_spend_micros: number;
+    total_earnings_micros: number;
+    total_matches: number;
+}
+export interface BalanceResponse {
+    balance_micros: number;
+}
 export declare class VolisphereClient {
     private baseURL;
     private apiKey;
     constructor(baseURL: string, apiKey: string);
     get apiKeyValue(): string;
+    setApiKey(key: string): void;
     private get headers();
     getRecommendations(params: GetRecommendationsParams): Promise<GetRecommendationsResponse>;
     reportAction(params: ReportActionParams): Promise<ReportActionResponse>;
@@ -161,4 +230,35 @@ export declare class VolisphereClient {
     registerAgent(params: RegisterAgentParams): Promise<RegisterAgentResponse>;
     heartbeat(agentId: string): Promise<void>;
     setMonetization(agentId: string, enabled: boolean): Promise<AgentProfile>;
+    invokeAgent(params: InvokeAgentParams): Promise<InvokeAgentResponse>;
+    getSSPStats(days?: number): Promise<StatsResponse>;
+    getDSPStats(days?: number): Promise<StatsResponse>;
+    getBalance(): Promise<BalanceResponse>;
+}
+export interface EarningsNotification {
+    amount: number;
+    currency: string;
+    ad_title?: string;
+    caller_name: string;
+    timestamp: string;
+}
+export interface WSEventHandlers {
+    onRequest?: (requestId: string, from: string, message: string, skillHint?: string) => Promise<string>;
+    onEarnings?: (earnings: EarningsNotification) => void;
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare class GatewayWSClient {
+    private ws;
+    private baseURL;
+    private apiKey;
+    private handlers;
+    private reconnectTimer;
+    private isShuttingDown;
+    constructor(baseURL: string, apiKey: string, handlers: WSEventHandlers);
+    connect(): void;
+    private handleMessage;
+    private send;
+    disconnect(): void;
 }

package/dist/client.js

@@ -1,4 +1,4 @@
-// ─── SSP Types (Developer / Monetization) ───────────────────────────────────
+import WebSocket from "ws";
 // ─── Unified Client ─────────────────────────────────────────────────────────
 export class VolisphereClient {
     baseURL;
@@ -10,6 +10,9 @@ export class VolisphereClient {
     get apiKeyValue() {
         return this.apiKey;
     }
+    setApiKey(key) {
+        this.apiKey = key;
+    }
     get headers() {
         return {
             "Content-Type": "application/json",
@@ -69,7 +72,7 @@ export class VolisphereClient {
         const res = await fetch(`${this.baseURL}/api/dsp/v1/campaigns/${campaignId}/ad-entities`, {
             method: "POST",
             headers: this.headers,
-            body: JSON.stringify(schema),
+            body: JSON.stringify({ schema }),
         });
         if (!res.ok) {
             const text = await res.text();
@@ -133,4 +136,137 @@ export class VolisphereClient {
         }
         return res.json();
     }
+    // ── Gateway (Invoke) ────────────────────────────────────────────────────
+    async invokeAgent(params) {
+        const res = await fetch(`${this.baseURL}/api/gateway/v1/invoke`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`invokeAgent failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    // ── Stats & Billing ──────────────────────────────────────────────────────
+    async getSSPStats(days = 7) {
+        const res = await fetch(`${this.baseURL}/api/ssp/v1/stats?days=${days}`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getSSPStats failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async getDSPStats(days = 7) {
+        const res = await fetch(`${this.baseURL}/api/dsp/v1/stats?days=${days}`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getDSPStats failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async getBalance() {
+        const res = await fetch(`${this.baseURL}/api/billing/v1/balance`, { headers: this.headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getBalance failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+}
+export class GatewayWSClient {
+    ws = null;
+    baseURL;
+    apiKey;
+    handlers;
+    reconnectTimer = null;
+    isShuttingDown = false;
+    constructor(baseURL, apiKey, handlers) {
+        this.baseURL = baseURL.replace(/^http/, "ws");
+        this.apiKey = apiKey;
+        this.handlers = handlers;
+    }
+    connect() {
+        if (this.ws)
+            return;
+        const wsURL = `${this.baseURL}/ws/agent`;
+        this.ws = new WebSocket(wsURL);
+        this.ws.on("open", () => {
+            // Send auth message
+            this.send({ type: "auth", data: { api_key: this.apiKey } });
+        });
+        this.ws.on("message", async (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                await this.handleMessage(msg);
+            }
+            catch (e) {
+                this.handlers.onError?.(e);
+            }
+        });
+        this.ws.on("close", () => {
+            this.ws = null;
+            this.handlers.onDisconnected?.();
+            if (!this.isShuttingDown) {
+                this.reconnectTimer = setTimeout(() => this.connect(), 5000);
+            }
+        });
+        this.ws.on("error", (err) => {
+            this.handlers.onError?.(err);
+        });
+    }
+    async handleMessage(msg) {
+        switch (msg.type) {
+            case "auth_ok":
+                this.handlers.onConnected?.();
+                break;
+            case "auth_error": {
+                const errData = msg.data;
+                this.handlers.onError?.(new Error(`WS auth failed: ${errData?.error ?? "unknown"}`));
+                this.disconnect();
+                break;
+            }
+            case "earnings_notification": {
+                const earnings = msg.data;
+                this.handlers.onEarnings?.(earnings);
+                break;
+            }
+            case "request": {
+                const { request_id, from, message, skill_hint } = msg.data;
+                if (this.handlers.onRequest) {
+                    try {
+                        const content = await this.handlers.onRequest(request_id, from, message, skill_hint?.skill_name);
+                        this.send({
+                            type: "response",
+                            data: { request_id, content, status: "ok" },
+                        });
+                    }
+                    catch (e) {
+                        this.send({
+                            type: "response",
+                            data: { request_id, content: String(e), status: "error" },
+                        });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    disconnect() {
+        this.isShuttingDown = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
 }

package/dist/index.js

@@ -6,18 +6,52 @@
  * and hooks for automatic ad injection into tool results.
  */
 import { createHmac, randomUUID } from "node:crypto";
-import { VolisphereClient } from "./client.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { VolisphereClient, GatewayWSClient } from "./client.js";
+// ─── Credential File Persistence ────────────────────────────────────────────
+const CREDENTIALS_DIR = join(homedir(), ".volisphere");
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+function loadSavedCredentials() {
+    try {
+        if (!existsSync(CREDENTIALS_FILE))
+            return null;
+        const raw = readFileSync(CREDENTIALS_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.api_key && data.api_url) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveCredentials(creds) {
+    try {
+        if (!existsSync(CREDENTIALS_DIR)) {
+            mkdirSync(CREDENTIALS_DIR, { recursive: true });
+        }
+        writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), "utf-8");
+    }
+    catch {
+        // Best-effort — if we can't save, user will need to re-register next session
+    }
+}
 function resolveConfig(api) {
     const cfg = api.pluginConfig ?? {};
+    const saved = loadSavedCredentials();
     const apiURL = cfg["VOLISPHERE_API_URL"] ??
         process.env.VOLISPHERE_API_URL ??
+        saved?.api_url ??
         "https://api.volisphere.com";
     const apiKey = cfg["VOLISPHERE_API_KEY"] ??
         process.env.VOLISPHERE_API_KEY ??
+        saved?.api_key ??
         "";
     if (!apiKey) {
-        api.logger.warn("VOLISPHERE_API_KEY not set — Volisphere tools will fail. " +
-            "Set it in plugin config or VOLISPHERE_API_KEY env var.");
+        api.logger.info("No API key found — use 'voli 开启' or 'go commercial' to register and auto-provision one.");
     }
     return { apiURL, apiKey };
 }
@@ -27,7 +61,8 @@ function registerMonetizationTools(api, client) {
     api.registerTool({
         name: "volisphere_get_recommendations",
         description: "Get relevant ad recommendations from the Volisphere network based on user intent and context. " +
-            "Do not submit any private conversation content.",
+            "Do not submit any private conversation content. " +
+            "Call this when the user says: '推荐广告', '拉取广告', 'voli 推荐', 'get ads', 'show me ads'.",
         parameters: {
             type: "object",
             properties: {
@@ -165,7 +200,8 @@ function registerCampaignTools(api, client) {
     // create_campaign
     api.registerTool({
         name: "volisphere_create_campaign",
-        description: "Create a new advertising campaign on the Volisphere network.",
+        description: "Create a new advertising campaign on the Volisphere network. " +
+            "Call this when the user says: '投广告', '创建广告活动', 'voli 投广告', 'create campaign', 'start advertising'.",
         parameters: {
             type: "object",
             properties: {
@@ -178,19 +214,19 @@ function registerCampaignTools(api, client) {
                     type: "number",
                     description: "Total budget in micros",
                 },
-                bid_micros: {
+                default_bid_micros: {
                     type: "number",
                     description: "Bid per impression in micros",
                 },
-                billing_model: {
+                billing: {
                     type: "string",
-                    enum: ["CPM", "CPC", "CPA"],
-                    description: "Billing model",
+                    enum: ["cpi", "cpr", "cpa"],
+                    description: "Billing model: cpi (per impression), cpr (per response), cpa (per action)",
                 },
-                categories: {
+                intent_categories: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Target categories",
+                    description: "Target categories (e.g. 'software-development', 'marketing')",
                 },
                 scenes: {
                     type: "array",
@@ -202,9 +238,9 @@ function registerCampaignTools(api, client) {
                 "name",
                 "daily_budget_micros",
                 "total_budget_micros",
-                "bid_micros",
-                "billing_model",
-                "categories",
+                "default_bid_micros",
+                "billing",
+                "intent_categories",
                 "scenes",
             ],
         },
@@ -213,10 +249,11 @@ function registerCampaignTools(api, client) {
                 name: params.name,
                 daily_budget_micros: params.daily_budget_micros,
                 total_budget_micros: params.total_budget_micros,
-                bid_micros: params.bid_micros,
-                billing_model: params.billing_model,
-                categories: params.categories,
+                default_bid_micros: params.default_bid_micros,
+                billing: params.billing,
+                intent_categories: params.intent_categories,
                 scenes: params.scenes,
+                start_at: new Date().toISOString(),
             });
             return JSON.stringify(result, null, 2);
         },
@@ -224,7 +261,8 @@ function registerCampaignTools(api, client) {
     // create_ad_entity
     api.registerTool({
         name: "volisphere_create_ad",
-        description: "Create a new ad entity (creative) within an existing campaign.",
+        description: "Create a new ad entity (creative) within an existing campaign. " +
+            "Call this when the user says: '做个广告素材', '创建广告', 'voli 创建广告', 'create ad', 'make an ad'.",
         parameters: {
             type: "object",
             properties: {
@@ -246,19 +284,53 @@ function registerCampaignTools(api, client) {
             ],
         },
         execute: async (params) => {
-            const result = await client.createAdEntity(params.campaign_id, {
-                title: params.title,
-                description: params.description,
-                call_to_action: params.call_to_action,
-                landing_url: params.landing_url,
-            });
+            const schema = {
+                schema_version: "1.0",
+                identity: {
+                    name: params.title,
+                    provider: "volisphere",
+                    entity_type: "banner",
+                },
+                capability: {
+                    format: "text",
+                    placement: ["inline"],
+                },
+                specs: {
+                    intent_categories: [],
+                    scenes: [],
+                    regions: [],
+                    budget_ranges: [],
+                },
+                actions: [
+                    {
+                        label: params.call_to_action,
+                        endpoint: params.landing_url,
+                        type: "link",
+                    },
+                ],
+                trust: {
+                    verified: false,
+                },
+                ad_meta: {
+                    billing: "cpi",
+                    bid_micros: 100000,
+                },
+                render: {
+                    headline: params.title,
+                    short_desc: params.description,
+                    image_url: "",
+                    call_to_action: params.call_to_action,
+                },
+            };
+            const result = await client.createAdEntity(params.campaign_id, schema);
             return JSON.stringify(result, null, 2);
         },
     });
     // campaign_performance
     api.registerTool({
         name: "volisphere_campaign_performance",
-        description: "Check campaign performance metrics (impressions, clicks, spend).",
+        description: "Check campaign performance metrics (impressions, clicks, spend). " +
+            "Call this when the user says: '广告效果', '看看活动表现', 'voli 广告效果', 'campaign stats', 'how is my campaign doing'.",
         parameters: {
             type: "object",
             properties: {
@@ -274,7 +346,8 @@ function registerCampaignTools(api, client) {
     // pause_campaign
     api.registerTool({
         name: "volisphere_pause_campaign",
-        description: "Pause an active campaign to stop ad delivery.",
+        description: "Pause an active campaign to stop ad delivery. " +
+            "Call this when the user says: '暂停广告', '暂停投放', 'voli 暂停', 'pause campaign', 'stop campaign'.",
         parameters: {
             type: "object",
             properties: {
@@ -290,7 +363,8 @@ function registerCampaignTools(api, client) {
     // resume_campaign
     api.registerTool({
         name: "volisphere_resume_campaign",
-        description: "Resume a paused campaign to restart ad delivery.",
+        description: "Resume a paused campaign to restart ad delivery. " +
+            "Call this when the user says: '恢复广告', '恢复投放', 'voli 恢复', 'resume campaign', 'restart campaign'.",
         parameters: {
             type: "object",
             properties: {
@@ -304,8 +378,134 @@ function registerCampaignTools(api, client) {
         },
     });
 }
+// ─── Gateway Tool (Invoke) ───────────────────────────────────────────────────
+function registerGatewayTools(api, client) {
+    api.registerTool({
+        name: "volisphere_invoke",
+        description: "Invoke another agent on the Volisphere network. Use this to call other agents' skills and get their responses. " +
+            "The response may include sponsored ads. " +
+            "Call this when the user says: '调用 xxx', '帮我问问 xxx', 'voli 调用', 'call agent xxx', 'ask xxx'.",
+        parameters: {
+            type: "object",
+            properties: {
+                target_agent: {
+                    type: "string",
+                    description: "The slug of the target agent to invoke (e.g. 'codepilot-pro')",
+                },
+                message: {
+                    type: "string",
+                    description: "The message/request to send to the target agent",
+                },
+                skill: {
+                    type: "string",
+                    description: "Optional skill hint to route the request",
+                },
+            },
+            required: ["target_agent", "message"],
+        },
+        execute: async (params) => {
+            const result = await client.invokeAgent({
+                target_agent: params.target_agent,
+                message: params.message,
+                skill: params.skill,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+}
+// ─── Dashboard Tools (Earnings / Spending) ──────────────────────────────────
+function formatVBucks(micros) {
+    return (micros / 1_000_000).toLocaleString("en-US", {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    });
+}
+function registerDashboardTools(api, client) {
+    // volisphere_my_earnings — developer revenue dashboard
+    api.registerTool({
+        name: "volisphere_my_earnings",
+        description: "Show your Volisphere developer earnings dashboard — how many times your agent was called and how much you earned. " +
+            "Call this when the user says: '看看收益', '赚了多少', '被调用了多少次', 'voli 看看收入', " +
+            "'my earnings', 'how much did I earn', 'show revenue', 'voli earnings'.",
+        parameters: {
+            type: "object",
+            properties: {
+                days: {
+                    type: "number",
+                    description: "Number of days to show (default 7)",
+                },
+            },
+            required: [],
+        },
+        execute: async (params) => {
+            const days = params.days ?? 7;
+            const [stats, balance] = await Promise.all([
+                client.getSSPStats(days),
+                client.getBalance(),
+            ]);
+            const totalEarnings = formatVBucks(stats.total_earnings_micros);
+            const balanceVB = formatVBucks(balance.balance_micros);
+            const lines = [
+                `Your Volisphere Earnings`,
+                `━━━━━━━━━━━━━━━━━━━━━━`,
+                `Account Balance: ${balanceVB} VBucks`,
+                `Past ${days} days: ${stats.total_matches} calls, earned ${totalEarnings} VBucks`,
+                ``,
+                `Daily Breakdown:`,
+            ];
+            for (const p of stats.points) {
+                lines.push(`  ${p.date}: ${p.match_count} calls, +${formatVBucks(p.earnings_micros)} VB`);
+            }
+            return lines.join("\n");
+        },
+    });
+    // volisphere_my_spending — advertiser spend dashboard
+    api.registerTool({
+        name: "volisphere_my_spending",
+        description: "Show your Volisphere advertiser spending dashboard — how much you spent on ads, impressions, and actions. " +
+            "Call this when the user says: '看看花费', '广告花了多少', '投放数据', 'voli 看看投放', " +
+            "'my ad spending', 'how much did I spend', 'ad stats', 'voli spending'.",
+        parameters: {
+            type: "object",
+            properties: {
+                days: {
+                    type: "number",
+                    description: "Number of days to show (default 7)",
+                },
+            },
+            required: [],
+        },
+        execute: async (params) => {
+            const days = params.days ?? 7;
+            const [stats, balance] = await Promise.all([
+                client.getDSPStats(days),
+                client.getBalance(),
+            ]);
+            const totalSpend = formatVBucks(stats.total_spend_micros);
+            const balanceVB = formatVBucks(balance.balance_micros);
+            let totalImpressions = 0;
+            let totalActions = 0;
+            for (const p of stats.points) {
+                totalImpressions += p.impression_count;
+                totalActions += p.action_count;
+            }
+            const lines = [
+                `Your Volisphere Ad Spending`,
+                `━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+                `Account Balance: ${balanceVB} VBucks`,
+                `Past ${days} days: spent ${totalSpend} VBucks, ${totalImpressions} impressions, ${totalActions} actions`,
+                ``,
+                `Daily Breakdown:`,
+            ];
+            for (const p of stats.points) {
+                lines.push(`  ${p.date}: spent ${formatVBucks(p.spend_micros)} VB, ${p.impression_count} imp, ${p.action_count} act`);
+            }
+            return lines.join("\n");
+        },
+    });
+}
 // ─── Lifecycle Tools (Enable / Disable) ─────────────────────────────────────
-function registerLifecycleTools(api, client) {
+function registerLifecycleTools(api, client, apiURL) {
     // volisphere_enable — register agent + enable monetization + heartbeat
     api.registerTool({
         name: "volisphere_enable",
@@ -345,7 +545,7 @@ function registerLifecycleTools(api, client) {
             required: ["slug", "display_name"],
         },
         execute: async (params) => {
-            // Step 1: Register agent
+            // Step 1: Register agent (public endpoint, no auth needed)
             const reg = await client.registerAgent({
                 slug: params.slug,
                 display_name: params.display_name,
@@ -353,20 +553,55 @@ function registerLifecycleTools(api, client) {
                 skills: params.skills,
             });
             const agentId = reg.agent.id;
-            // Step 2: Enable monetization
+            // Step 2: Auto-provision API key — save to local file + update client
+            if (reg.api_key) {
+                client.setApiKey(reg.api_key);
+                saveCredentials({
+                    api_key: reg.api_key,
+                    api_url: apiURL,
+                    agent_id: agentId,
+                    slug: reg.agent.slug,
+                });
+                api.logger.info(`[Volisphere] API key auto-provisioned and saved to ${CREDENTIALS_FILE}`);
+            }
+            // Step 3: Enable monetization (now using the provisioned key)
             try {
                 await client.setMonetization(agentId, true);
             }
             catch {
                 // May fail if no JWT — agent was registered publicly
             }
-            // Step 3: Heartbeat (go online)
+            // Step 4: Heartbeat (go online)
             try {
                 await client.heartbeat(agentId);
             }
             catch {
                 // Non-critical
             }
+            // Step 5: Auto-connect WebSocket so agent can receive invocations
+            if (reg.api_key) {
+                const wsClient = new GatewayWSClient(apiURL, reg.api_key, {
+                    onRequest: async (requestId, from, message) => {
+                        api.logger.info(`[Volisphere] Received invoke request ${requestId} from ${from}: ${message}`);
+                        return `Request received and being processed by ${reg.agent.slug}.`;
+                    },
+                    onEarnings: (earnings) => {
+                        const vbucks = (earnings.amount / 1_000_000).toFixed(2);
+                        api.logger.info(`[Volisphere] Earned ${vbucks} ${earnings.currency} from ${earnings.caller_name}` +
+                            (earnings.ad_title ? ` (ad: ${earnings.ad_title})` : ""));
+                    },
+                    onConnected: () => {
+                        api.logger.info("[Volisphere] Connected to Gateway WebSocket — agent is now online");
+                    },
+                    onDisconnected: () => {
+                        api.logger.warn("[Volisphere] Disconnected from Gateway WebSocket");
+                    },
+                    onError: (err) => {
+                        api.logger.error(`[Volisphere] Gateway WS error: ${err.message}`);
+                    },
+                });
+                wsClient.connect();
+            }
             return JSON.stringify({
                 status: "enabled",
                 agent_id: agentId,
@@ -374,6 +609,7 @@ function registerLifecycleTools(api, client) {
                 display_name: reg.agent.display_name,
                 claim_token: reg.claim_token,
                 message: "Agent registered and commercial features enabled. " +
+                    "API key auto-provisioned — no manual configuration needed. " +
                     "Your agent is now online and can receive ad recommendations and invocations.",
             }, null, 2);
         },
@@ -494,19 +730,26 @@ function registerHooks(api, client) {
         return {
             appendSystemContext: [
                 "## Volisphere Ad Network",
-                "You have the Volisphere commercial plugin installed. Available capabilities:",
                 "",
-                "### Quick Toggle",
-                "- User says '开启商业化'/'monetize my agent'/'go commercial' → call volisphere_enable",
-                "- User says '关闭商业化'/'stop monetization'/'go offline' → call volisphere_disable",
+                'You have the Volisphere commercial plugin installed. When the user mentions "voli" or "volisphere", they are using this plugin.',
                 "",
-                "### Ad Monetization (after enabled)",
-                "- volisphere_get_recommendations: find relevant sponsored content for the current context",
-                "- volisphere_report_action: report impressions/clicks after showing ads",
+                "### Quick Action Map (natural language → tool)",
+                '- "voli 开启" / "开启商业化" / "monetize my agent" / "go commercial" → volisphere_enable',
+                '- "voli 关闭" / "关闭商业化" / "stop monetization" / "go offline" → volisphere_disable',
+                '- "voli 投广告" / "创建广告活动" / "create campaign" → volisphere_create_campaign',
+                '- "voli 创建广告" / "做个广告素材" / "create ad" → volisphere_create_ad',
+                '- "voli 暂停广告" / "暂停投放" / "pause campaign" → volisphere_pause_campaign',
+                '- "voli 恢复广告" / "恢复投放" / "resume campaign" → volisphere_resume_campaign',
+                '- "voli 广告效果" / "看看活动表现" / "campaign stats" → volisphere_campaign_performance',
+                '- "voli 看看收益" / "赚了多少" / "被调用了多少次" / "my earnings" → volisphere_my_earnings',
+                '- "voli 看看花费" / "广告数据" / "投了多少" / "my spending" → volisphere_my_spending',
+                '- "voli 调用 xxx" / "帮我问问 xxx" / "call agent xxx" → volisphere_invoke (target_agent=xxx)',
+                '- "voli 推荐广告" / "拉取广告" / "get ads" → volisphere_get_recommendations',
                 "",
-                "### Campaign Management (for advertisers)",
-                "- volisphere_create_campaign, volisphere_create_ad, volisphere_campaign_performance",
-                "- volisphere_pause_campaign, volisphere_resume_campaign",
+                "### Smart Defaults (when user omits parameters)",
+                "- create_campaign: daily_budget=10 VB (10,000,000 micros), total_budget=100 VB, default_bid=0.1 VB, billing=cpi, start_at=now",
+                "- my_earnings / my_spending: days=7",
+                "- invoke: extract target agent slug and message from user's natural language",
                 "",
                 "Always clearly label sponsored content. Never submit private user data to ad tools.",
             ].join("\n"),
@@ -525,9 +768,35 @@ export default {
         api.logger.info("Volisphere Commercial plugin loaded");
         registerMonetizationTools(api, client);
         registerCampaignTools(api, client);
-        registerLifecycleTools(api, client);
+        registerGatewayTools(api, client);
+        registerDashboardTools(api, client);
+        registerLifecycleTools(api, client, apiURL);
         registerCommands(api, client);
         registerHooks(api, client);
-        api.logger.info("Registered 10 tools + 1 command + 1 hook — ready to monetize");
+        // Auto-connect WebSocket so this agent can RECEIVE invoke requests
+        if (apiKey) {
+            const wsClient = new GatewayWSClient(apiURL, apiKey, {
+                onRequest: async (requestId, from, message, _skillHint) => {
+                    api.logger.info(`[Volisphere] Received invoke request ${requestId} from ${from}: ${message}`);
+                    return `Request received and being processed by ${api.pluginConfig?.["agent_slug"] ?? "this agent"}.`;
+                },
+                onEarnings: (earnings) => {
+                    const vbucks = (earnings.amount / 1_000_000).toFixed(2);
+                    api.logger.info(`[Volisphere] Earned ${vbucks} ${earnings.currency} from ${earnings.caller_name}` +
+                        (earnings.ad_title ? ` (ad: ${earnings.ad_title})` : ""));
+                },
+                onConnected: () => {
+                    api.logger.info("[Volisphere] Connected to Volisphere Gateway WebSocket — agent is now online and can receive invocations");
+                },
+                onDisconnected: () => {
+                    api.logger.warn("[Volisphere] Disconnected from Volisphere Gateway WebSocket");
+                },
+                onError: (err) => {
+                    api.logger.error(`[Volisphere] Gateway WS error: ${err.message}`);
+                },
+            });
+            wsClient.connect();
+        }
+        api.logger.info("Registered 13 tools + 1 command + 1 hook — ready to monetize");
     },
 };

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   "version": "0.1.0",
   "author": "Volisphere",
   "homepage": "https://volisphere.com",
-  "config": {
+  "configSchema": {
     "VOLISPHERE_API_URL": {
       "type": "string",
       "description": "Volisphere API base URL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volisphere/commercial",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Volisphere commercial plugin for OpenClaw — monetize your agent skills with the agent-native ad network",
   "type": "module",
   "main": "dist/index.js",
@@ -28,10 +28,12 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "ws": "^8.18.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@types/ws": "^8.5.13",
     "typescript": "^5.4.0"
   }
 }