clawaxis 1.0.0

package/src/channel.ts

@@ -0,0 +1,78 @@
+import { LOG_PREFIX, loadConfig } from "./config.js";
+import { setUtilsConfig, relayFetch } from "./utils.js";
+import { createWebSocketService } from "./websocket.js";
+
+export const clawaxisChannel = {
+  id: "clawaxis",
+  meta: {
+    id: "clawaxis",
+    label: "ClawAxis",
+    selectionLabel: "ClawAxis (Mobile)",
+    blurb: "Control your OpenClaw agent from the ClawAxis mobile app.",
+    aliases: ["sc"],
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+  },
+  config: {
+    listAccountIds: (cfg: any) =>
+      Object.keys(cfg.channels?.clawaxis?.accounts ?? {}),
+    resolveAccount: (cfg: any, accountId: string) =>
+      cfg.channels?.clawaxis?.accounts?.[accountId ?? "default"] ?? {
+        accountId,
+      },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async () => ({ ok: true }),
+    sendMedia: async (ctx: any) => {
+      const result = await relayFetch("POST", "message", {
+        content: ctx.caption || "[media]",
+        message_type: "image",
+      });
+      return { ok: !!result };
+    },
+  },
+
+  gateway: {
+    /**
+     * OpenClaw calls startAccount when the channel activates.
+     * This is the correct lifecycle hook for channel plugins —
+     * it replaces manual api.registerService() + wsService.start().
+     *
+     * ctx.account.config is pre-scoped to the channel config
+     * (relayUrl/agentToken already at top level).
+     *
+     * Returns a cleanup function that OpenClaw calls on shutdown.
+     */
+    startAccount: async (ctx: any) => {
+      const accountId = ctx.account?.accountId || "default";
+      console.log(`${LOG_PREFIX} gateway.startAccount called for account: ${accountId}`);
+
+      const accountConfig = ctx.account?.config || ctx.config;
+      const config = loadConfig(accountConfig);
+
+      if (!config) {
+        console.warn(`${LOG_PREFIX} No valid config for account ${accountId}, skipping WebSocket start`);
+        return () => {};
+      }
+
+      setUtilsConfig(config);
+
+      console.log(`${LOG_PREFIX} \u2713 Config loaded for account ${accountId}`);
+      if (config.mediaDomain) console.log(`${LOG_PREFIX}   \u2022 Media domain: ${config.mediaDomain}`);
+      if (config.agentName) console.log(`${LOG_PREFIX}   \u2022 Agent name: ${config.agentName}`);
+
+      const wsService = createWebSocketService(config);
+      await wsService.start();
+
+      console.log(`${LOG_PREFIX} \u2713 Account ${accountId} started (WebSocket active)`);
+
+      return async () => {
+        console.log(`${LOG_PREFIX} Stopping account ${accountId}...`);
+        await wsService.stop();
+        console.log(`${LOG_PREFIX} \u2713 Account ${accountId} stopped`);
+      };
+    },
+  },
+};

package/src/config.ts

@@ -0,0 +1,82 @@
+import type { GovernanceConfig, ClawAxisConfig } from "./types.js";
+
+export const HEARTBEAT_MS = 60000;
+export const PING_MS = 30000;
+export const REAUTH_BUFFER_MS = 5000;
+export const MAX_RECONNECT_DELAY = 60000;
+export const LOG_PREFIX = "\u{1F99E}";
+export const PLUGIN_VERSION = "2.0.0";
+
+// Supabase anon key (public by design — RLS enforces security, not key secrecy)
+export const ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImZxd3B3eXB5emNibWRlYWpsa3p0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzA2NDUxOTIsImV4cCI6MjA4NjIyMTE5Mn0.Dc_gve3L8tMXPMqWZQYq-gxCCdPnm7Z5W6A9fg0pLis";
+
+export const DEFAULT_GOVERNANCE: GovernanceConfig = {
+  imageTools: [],
+  contentTools: [
+    "clawaxis_post_content",
+    "clawaxis_update_content"
+  ],
+  publishingTools: [
+    "clawaxis_post_content",
+    "clawaxis_update_content"
+  ],
+  memorySearch: {
+    contentQuery: "{content_type} style guide writing tone brand voice",
+    imageQuery: "image style guide brand visual aesthetic colors",
+    maxResults: 5,
+    minScore: 0.65,
+    cacheDurationMs: 300000
+  },
+  validation: {
+    requireCTA: false,
+    requirePermanentImages: false,
+    requireValidAuthor: false,
+    allowedContentTypes: ["twitter", "instagram", "linkedin", "facebook", "tiktok", "youtube", "blog", "report", "email", "ad", "website", "document", "other"]
+  },
+  logging: {
+    enabled: true,
+    logAllTools: false,
+    logGovernanceIssues: true,
+    debounceMs: 100
+  }
+};
+
+/**
+ * Load and merge config from OpenClaw's config hierarchy.
+ *
+ * Supports three paths:
+ *   1. Pre-scoped config (from gateway.startAccount ctx.account.config) —
+ *      already has relayUrl/agentToken at top level
+ *   2. channels.clawaxis — primary location in openclaw.json
+ *   3. plugins.entries.clawaxis-plugin.config — backward compat
+ */
+export function loadConfig(apiConfig: any): ClawAxisConfig | null {
+  let cfg: any;
+
+  if (apiConfig?.relayUrl && apiConfig?.agentToken) {
+    cfg = apiConfig;
+  } else {
+    cfg = apiConfig?.channels?.clawaxis
+      ?? apiConfig?.plugins?.entries?.["clawaxis-plugin"]?.config;
+  }
+
+  if (!cfg) return null;
+  if (!cfg.relayUrl || !cfg.agentToken) return null;
+
+  const governance: GovernanceConfig = {
+    imageTools: cfg.governance?.imageTools || DEFAULT_GOVERNANCE.imageTools,
+    contentTools: cfg.governance?.contentTools || DEFAULT_GOVERNANCE.contentTools,
+    publishingTools: cfg.governance?.publishingTools || DEFAULT_GOVERNANCE.publishingTools,
+    memorySearch: { ...DEFAULT_GOVERNANCE.memorySearch, ...(cfg.governance?.memorySearch || {}) },
+    validation: { ...DEFAULT_GOVERNANCE.validation, ...(cfg.governance?.validation || {}) },
+    logging: { ...DEFAULT_GOVERNANCE.logging, ...(cfg.governance?.logging || {}) }
+  };
+
+  return {
+    relayUrl: cfg.relayUrl,
+    agentToken: cfg.agentToken,
+    mediaDomain: cfg.mediaDomain || null,
+    agentName: apiConfig?.agents?.defaults?.name || cfg.agentName || null,
+    governance,
+  };
+}

package/src/governance/hooks.ts

@@ -0,0 +1,92 @@
+import { LOG_PREFIX } from "../config.js";
+import { getFlushTimeout, setFlushTimeout } from "../runtime.js";
+import { flushLogQueue } from "../utils.js";
+import { logToolCall } from "./logging.js";
+import { injectStyleDocs } from "./style-injection.js";
+import { enforceGovernance } from "./validation.js";
+import type { HookContext, ClawAxisConfig } from "../types.js";
+
+const ENHANCEMENT_TIMEOUT_MS = 5000;
+
+function withTimeout<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((resolve) => setTimeout(() => resolve(fallback), ms)),
+  ]);
+}
+
+export function registerGovernanceHooks(api: any, config: ClawAxisConfig) {
+  const governance = config.governance;
+
+  if (typeof api.registerHook !== "function") {
+    console.warn(`${LOG_PREFIX} api.registerHook not available, skipping governance hooks`);
+    return;
+  }
+
+  console.log(`${LOG_PREFIX} \uD83D\uDEE1\uFE0F  Registering governance hooks...`);
+
+  try {
+    api.registerHook("before_tool_call", {
+      name: "clawaxis-governance-before",
+      handler: async (context: HookContext) => {
+        try {
+          context.api = context.api || api;
+
+          // Layer 1 (logging) and Layer 2 (style injection) are independent — run in parallel.
+          // Layer 3 (validation) depends on injection results, so it runs after.
+          // Entire enhancement is capped at ENHANCEMENT_TIMEOUT_MS to avoid stalling the agent.
+          const enhanced = await withTimeout(
+            (async () => {
+              await Promise.all([
+                logToolCall(context, "before", governance),
+                injectStyleDocs(context, governance),
+              ]);
+              await enforceGovernance(context, governance, config.agentName, config.mediaDomain);
+              return context;
+            })(),
+            ENHANCEMENT_TIMEOUT_MS,
+            context,
+          );
+
+          return enhanced;
+        } catch (err) {
+          if (err instanceof Error && err.message.includes("[ClawAxis Governance]")) {
+            throw err;
+          }
+          console.error(`${LOG_PREFIX} before_tool_call hook failed:`, err);
+          return context;
+        }
+      }
+    });
+
+    api.registerHook("after_tool_call", {
+      name: "clawaxis-governance-after",
+      handler: async (context: HookContext) => {
+        try {
+          // Fire-and-forget: logging should never block the agent turn
+          logToolCall(context, "after", governance).catch((err) => {
+            console.error(`${LOG_PREFIX} after_tool_call log failed:`, err);
+          });
+
+          const ft = getFlushTimeout();
+          if (ft) {
+            clearTimeout(ft);
+            setFlushTimeout(null);
+            flushLogQueue().catch((err) => {
+              console.error(`${LOG_PREFIX} Log flush failed:`, err);
+            });
+          }
+
+          return context;
+        } catch (err) {
+          console.error(`${LOG_PREFIX} after_tool_call hook failed:`, err);
+          return context;
+        }
+      }
+    });
+
+    console.log(`${LOG_PREFIX} \u2713 Governance hooks registered (2 hooks)`);
+  } catch (err) {
+    console.error(`${LOG_PREFIX} Failed to register governance hooks:`, err);
+  }
+}

package/src/governance/logging.ts

@@ -0,0 +1,58 @@
+import type { GovernanceConfig, HookContext } from "../types.js";
+import { relayLog } from "../utils.js";
+
+function isImageTool(toolName: string, governance: GovernanceConfig): boolean {
+  const lower = toolName.toLowerCase();
+  return governance.imageTools.some(pattern =>
+    lower.includes(pattern.toLowerCase())
+  );
+}
+
+function isContentTool(toolName: string, governance: GovernanceConfig): boolean {
+  return governance.contentTools.includes(toolName);
+}
+
+function isPublishingTool(toolName: string, governance: GovernanceConfig): boolean {
+  return governance.publishingTools.includes(toolName);
+}
+
+export async function logToolCall(
+  context: HookContext,
+  phase: "before" | "after",
+  governance: GovernanceConfig,
+): Promise<void> {
+  const { toolName, durationMs, success, error } = context;
+
+  const isClawaxisTool = toolName.startsWith("clawaxis_");
+  const isGovernanceTool = isImageTool(toolName, governance)
+    || isContentTool(toolName, governance)
+    || isPublishingTool(toolName, governance);
+
+  if (!governance.logging.logAllTools && !isClawaxisTool && !isGovernanceTool) return;
+
+  if (phase === "before") {
+    await relayLog(
+      "tool_call",
+      `Calling ${toolName}`,
+      "info",
+      { toolName, phase: "start" }
+    );
+  } else {
+    const level = success === false ? "error" : "success";
+    const duration = durationMs ? ` (${durationMs}ms)` : "";
+    const status = success === false ? "failed" : "completed";
+
+    await relayLog(
+      "tool_call",
+      `${toolName} ${status}${duration}`,
+      level,
+      {
+        toolName,
+        phase: "end",
+        durationMs,
+        success,
+        error: error ? error.message : undefined
+      }
+    );
+  }
+}

package/src/governance/style-injection.ts

@@ -0,0 +1,114 @@
+import { LOG_PREFIX } from "../config.js";
+import { getMemoryCache } from "../runtime.js";
+import { relayLog } from "../utils.js";
+import type { GovernanceConfig, HookContext } from "../types.js";
+
+function isContentTool(toolName: string, governance: GovernanceConfig): boolean {
+  return governance.contentTools.includes(toolName);
+}
+
+function isImageTool(toolName: string, governance: GovernanceConfig): boolean {
+  const lower = toolName.toLowerCase();
+  return governance.imageTools.some(pattern =>
+    lower.includes(pattern.toLowerCase())
+  );
+}
+
+async function searchMemory(
+  context: HookContext,
+  query: string,
+  governance: GovernanceConfig,
+): Promise<any[]> {
+  const session = context.sessionKey || context.agentId || "main";
+  const cacheKey = `${session}:${query}`;
+  const now = Date.now();
+  const cache = getMemoryCache();
+
+  const cached = cache.get(cacheKey);
+  if (cached && (now - cached.timestamp) < governance.memorySearch.cacheDurationMs) {
+    return cached.snippets;
+  }
+
+  try {
+    const result = await context.api?.gateway?.call("memory.search", {
+      agentId: context.agentId || "main",
+      query,
+      maxResults: governance.memorySearch.maxResults,
+      minScore: governance.memorySearch.minScore,
+    });
+
+    const snippets = result?.snippets || [];
+    cache.set(cacheKey, { snippets, timestamp: now });
+    return snippets;
+  } catch (err) {
+    console.error(`${LOG_PREFIX} Memory search failed:`, err);
+    return [];
+  }
+}
+
+export async function injectStyleDocs(
+  context: HookContext,
+  governance: GovernanceConfig,
+): Promise<HookContext> {
+  const { toolName, params } = context;
+
+  const isContent = isContentTool(toolName, governance);
+  const isImage = isImageTool(toolName, governance);
+
+  if (!isContent && !isImage) return context;
+
+  try {
+    let searchQuery: string;
+    if (isImage) {
+      searchQuery = governance.memorySearch.imageQuery;
+    } else {
+      const contentType = params?.content_type || "blog";
+      searchQuery = governance.memorySearch.contentQuery
+        .replace("{content_type}", contentType);
+    }
+
+    const snippets = await searchMemory(context, searchQuery, governance);
+    if (snippets.length === 0) return context;
+
+    const docsText = snippets
+      .map((s: any) => s.content)
+      .join("\n\n---\n\n");
+
+    if (isImage && params) {
+      const promptKeys = ["instructions", "prompt", "text", "description", "query"];
+      const promptKey = promptKeys.find(key => params[key]);
+      if (promptKey && params[promptKey]) {
+        const originalPrompt = params[promptKey];
+        params[promptKey] = `${originalPrompt}\n\nStyle reference from brand guidelines:\n${docsText}`;
+      }
+    }
+
+    if (isContent) {
+      context._injectedDocs = docsText;
+    }
+
+    await relayLog(
+      "content_generate",
+      `Injected ${snippets.length} reference doc chunk(s) for ${toolName}`,
+      "info",
+      {
+        toolName,
+        snippetCount: snippets.length,
+        docPaths: snippets.map((s: any) => s.path)
+      }
+    );
+  } catch (err) {
+    console.error(`${LOG_PREFIX} Style injection failed:`, err);
+
+    if (governance.logging.logGovernanceIssues) {
+      await relayLog(
+        "error",
+        `Style injection failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+        { toolName, error: err instanceof Error ? err.message : String(err) }
+      );
+    }
+  }
+
+  return context;
+}

package/src/governance/validation.ts

@@ -0,0 +1,206 @@
+import { LOG_PREFIX } from "../config.js";
+import { relayLog, flushLogQueue } from "../utils.js";
+import type { GovernanceConfig, ValidationIssue, HookContext } from "../types.js";
+
+export function validateContent(
+  params: any,
+  governance: GovernanceConfig,
+  agentName: string | null,
+  mediaDomain: string | null,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const body = params?.body || "";
+  const contentType = params?.content_type || "blog";
+
+  // Check 1: Valid content type
+  if (!governance.validation.allowedContentTypes.includes(contentType)) {
+    issues.push({
+      field: "content_type",
+      issue: `Invalid content_type '${contentType}'. Valid: ${governance.validation.allowedContentTypes.join(", ")}`,
+      severity: "error",
+      autofix: () => { params.content_type = "other"; }
+    });
+  }
+
+  // Check 2: Author attribution
+  if (governance.validation.requireValidAuthor && agentName) {
+    const agentNameLower = agentName.toLowerCase();
+    const bodyLower = body.toLowerCase();
+
+    const authorPatterns = [
+      `written by ${agentNameLower}`,
+      `by ${agentNameLower}`,
+      `author: ${agentNameLower}`,
+      `- ${agentNameLower}`,
+      `<meta name="author" content="${agentNameLower}"`,
+      `<span class="author">${agentNameLower}`
+    ];
+
+    if (authorPatterns.some(pattern => bodyLower.includes(pattern))) {
+      issues.push({
+        field: "body",
+        issue: `Author attribution uses agent name '${agentName}'. Must use the user's name (check user profile in memory).`,
+        severity: "error"
+      });
+    }
+  }
+
+  // Check 3: Image URLs must use configured media domain
+  if (governance.validation.requirePermanentImages && mediaDomain) {
+    const imgPatterns = [
+      /(?:src|content|data-src|poster)=["']([^"']*\.(?:png|jpg|jpeg|gif|webp|svg|avif)[^"']*)["']/gi,
+      /url\(["']?([^"')]*\.(?:png|jpg|jpeg|gif|webp|svg|avif)[^"')]*)[")]/gi
+    ];
+
+    for (const regex of imgPatterns) {
+      let match;
+      while ((match = regex.exec(body)) !== null) {
+        const imageUrl = match[1];
+        if (imageUrl.startsWith("data:") || imageUrl.startsWith("/") || imageUrl.startsWith("./")) continue;
+        if (!imageUrl.includes(mediaDomain)) {
+          issues.push({
+            field: "body",
+            issue: `Image URL uses external domain (must upload to ${mediaDomain} first): ${imageUrl.substring(0, 60)}...`,
+            severity: "error"
+          });
+        }
+      }
+    }
+  }
+
+  // Check 4: og:image meta tag
+  if (governance.validation.requirePermanentImages && mediaDomain) {
+    const ogMatch = body.match(/<meta\s+property=["']og:image["'][^>]*content=["']([^"']+)["']/i);
+    if (ogMatch && ogMatch[1]) {
+      const ogImageUrl = ogMatch[1];
+      if (!ogImageUrl.startsWith("data:") && !ogImageUrl.includes(mediaDomain)) {
+        issues.push({
+          field: "og:image",
+          issue: `og:image meta tag uses external URL. Should use ${mediaDomain} for permanent storage.`,
+          severity: "warning"
+        });
+      }
+    }
+  }
+
+  // Check 5: Call-to-action
+  if (governance.validation.requireCTA && (contentType === "website" || contentType === "blog")) {
+    const ctaPatterns = [
+      /\bjoin\s+(us|now|today)\b/i,
+      /\bsign\s*up\b/i,
+      /\bget\s*started\b/i,
+      /\btry\s+(it|now|free|for\s+free)\b/i,
+      /\bbeta\b/i,
+      /\bsubscribe\b/i,
+      /\blearn\s*more\b/i,
+      /\bcontact\s+(us|me)\b/i,
+      /\bdownload\b/i,
+      /\bregister\b/i,
+      /\bbook\s+a\s+(call|demo)\b/i,
+      /\brequest\s+(a\s+)?(demo|quote)\b/i,
+      /<a[^>]+class=["'][^"']*cta[^"']*["']/i,
+      /<button[^>]*>/i
+    ];
+
+    if (!ctaPatterns.some(pattern => pattern.test(body))) {
+      issues.push({
+        field: "body",
+        issue: "No call-to-action found. Blog and website content should include a CTA (button, link, or action phrase).",
+        severity: "warning"
+      });
+    }
+  }
+
+  // Check 6: Empty content — skip for social platforms
+  const socialTypes = ["twitter", "instagram", "facebook", "tiktok", "linkedin", "youtube"];
+  if (!socialTypes.includes(contentType) && (!body || body.trim().length < 100)) {
+    issues.push({
+      field: "body",
+      issue: "Content body is too short (minimum 100 characters recommended for long-form content).",
+      severity: "warning"
+    });
+  }
+
+  // Check 7: Missing title
+  if (!params?.title || params.title.trim().length === 0) {
+    issues.push({
+      field: "title",
+      issue: "Content title is missing or empty.",
+      severity: "error"
+    });
+  }
+
+  return issues;
+}
+
+export async function enforceGovernance(
+  context: HookContext,
+  governance: GovernanceConfig,
+  agentName: string | null,
+  mediaDomain: string | null,
+): Promise<HookContext> {
+  const { toolName, params } = context;
+
+  if (!governance.publishingTools.includes(toolName)) return context;
+
+  const issues = validateContent(params, governance, agentName, mediaDomain);
+
+  if (issues.length === 0) {
+    await relayLog("system", "\u2713 Content passed all governance checks", "success", { toolName });
+    return context;
+  }
+
+  const errors: ValidationIssue[] = [];
+  const warnings: ValidationIssue[] = [];
+  let autofixed = 0;
+
+  for (const issue of issues) {
+    if (issue.autofix) {
+      try {
+        issue.autofix();
+        autofixed++;
+        await relayLog("system", `Auto-fixed: ${issue.issue}`, "info", { field: issue.field });
+      } catch (err) {
+        console.error(`${LOG_PREFIX} Auto-fix failed:`, err);
+        errors.push(issue);
+      }
+    } else if (issue.severity === "error") {
+      errors.push(issue);
+    } else {
+      warnings.push(issue);
+    }
+  }
+
+  for (const warning of warnings) {
+    if (governance.logging.logGovernanceIssues) {
+      await relayLog("system", `Governance warning: ${warning.issue}`, "warning", { field: warning.field, toolName });
+    }
+  }
+
+  if (errors.length > 0) {
+    const errorList = errors.map(e => `- [${e.field}] ${e.issue}`).join("\n");
+
+    if (governance.logging.logGovernanceIssues) {
+      await relayLog(
+        "error",
+        `Content blocked by governance: ${errors.length} error(s)`,
+        "error",
+        { toolName, errorCount: errors.length, errors: errors.map(e => ({ field: e.field, issue: e.issue })) }
+      );
+    }
+
+    await flushLogQueue();
+    throw new Error(`[ClawAxis Governance] Content validation failed:\n\n${errorList}\n\nFix these issues and try again.`);
+  }
+
+  if (autofixed > 0 || warnings.length > 0) {
+    await relayLog(
+      "system",
+      `\u2713 Content passed governance (${autofixed} auto-fix, ${warnings.length} warning)`,
+      "info",
+      { toolName, autofixed, warnings: warnings.length }
+    );
+  }
+
+  return context;
+}