clawaxis 1.0.0

package/src/tools/memory.ts

@@ -0,0 +1,78 @@
+import { Type } from "@sinclair/typebox";
+import { ANON_KEY, LOG_PREFIX } from "../config.js";
+import { getAuthenticatedAgentId } from "../runtime.js";
+import { toolOk, toolFail } from "./helpers.js";
+
+let _agentToken = "";
+
+export function setMemoryAgentToken(token: string) {
+  _agentToken = token;
+}
+
+export function registerMemoryTools(api: any) {
+  api.registerTool({
+    name: "clawaxis_memory_search",
+    description: "Search ClawAxis governed memory store (Supabase pgvector). Use this for long-term memory recall: prior decisions, preferences, architecture, context from previous sessions. Returns semantically ranked memory chunks.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Semantic search query (e.g., 'ClawAxis architecture decisions', 'user preferences for memory')" }),
+      match_count: Type.Optional(Type.Number({ description: "Number of results to return. Default: 10, Max: 50" })),
+      match_threshold: Type.Optional(Type.Number({ description: "Minimum similarity score (0.0-1.0). Default: 0.5. Higher = more strict matching." })),
+    }),
+    async execute(_id: string, params: any) {
+      try {
+        const agent_id = getAuthenticatedAgentId() || "520bc407-81db-4ce3-85d5-d19bd437da0f";
+
+        const memoryApiUrl = "https://fqwpwypyzcbmdeajlkzt.supabase.co/functions/v1/memory-search";
+        const requestBody = {
+          query: params.query,
+          agent_id: agent_id,
+          match_count: params.match_count || 10,
+          match_threshold: params.match_threshold || 0.5
+        };
+
+        console.log(`${LOG_PREFIX} [Memory Search] Calling: ${memoryApiUrl}`);
+
+        const res = await fetch(memoryApiUrl, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${ANON_KEY}`,
+            "apikey": ANON_KEY,
+            "x-agent-token": _agentToken,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(requestBody)
+        });
+
+        console.log(`${LOG_PREFIX} [Memory Search] Response status: ${res.status}`);
+
+        if (!res.ok) {
+          const errorText = await res.text();
+          console.log(`${LOG_PREFIX} [Memory Search] Error response:`, errorText);
+          return toolFail(`Memory search failed: ${res.status} ${errorText}`, { error: errorText });
+        }
+
+        const result = await res.json();
+        console.log(`${LOG_PREFIX} [Memory Search] Result count: ${result?.results?.length || 0}`);
+
+        if (result?.results && result.results.length > 0) {
+          const snippets = result.results.map((r: any, i: number) =>
+            `[Result ${i + 1}] (Similarity: ${r.similarity?.toFixed(3)})\n${r.content}\n`
+          ).join("\n---\n\n");
+
+          return toolOk(`Found ${result.results.length} memories:\n\n${snippets}`, {
+            count: result.results.length,
+            results: result.results,
+          });
+        }
+
+        return toolOk(`No memories found. Raw response: ${JSON.stringify(result).substring(0, 500)}`, {
+          count: 0,
+          results: [],
+          raw: result,
+        });
+      } catch (err: any) {
+        return toolFail(`Memory search error: ${err.message}`, { error: err.message });
+      }
+    },
+  });
+}

package/src/tools/routines.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import { toolOk, toolFail, wsSendOrHttp } from "./helpers.js";
+
+export function registerRoutineTools(api: any) {
+  api.registerTool({
+    name: "clawaxis_notify_routine",
+    description: "Register a new routine/cron job in the ClawAxis app after creating it in OpenClaw. See CLAWAXIS.md for field details.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Short routine name (e.g., 'Daily AI News'). Displayed as the routine card title." }),
+      cron_expression: Type.String({ description: "Standard cron expression (e.g., '0 8 * * *' for daily at 8 AM)." }),
+      instruction: Type.String({ description: "What the routine does — the prompt/task description (e.g., 'Check AI news and post a summary blog post')." }),
+      openclaw_cron_id: Type.String({ description: "The OpenClaw cron job ID that was created." }),
+      next_run_at: Type.Optional(Type.String({ description: "ISO 8601 timestamp of next scheduled execution." })),
+      schedule_human: Type.Optional(Type.String({ description: "Human-readable schedule (e.g., 'Every day at 8:00 AM'). Shown in the app UI." })),
+      timezone: Type.Optional(Type.String({ description: "IANA timezone (e.g., 'America/New_York'). Default: America/New_York." })),
+      description: Type.Optional(Type.String({ description: "Longer description of what the routine accomplishes." })),
+      frequency: Type.Optional(Type.String({ description: "Must be: once, hourly, daily, weekly, monthly, or custom. Used for display grouping." })),
+      status: Type.Optional(Type.String({ description: "Must be: active, paused, or disabled. Default: active." })),
+    }),
+    async execute(_id: string, params: any) {
+      const result = await wsSendOrHttp(
+        { type: "routine_created", ...params },
+        "POST", "routine-created", params,
+      );
+      return result ? toolOk("Routine registered in app", { result }) : toolFail("Failed to register routine");
+    },
+  });
+
+  api.registerTool({
+    name: "clawaxis_update_routine",
+    description: "Update an existing routine in the ClawAxis app. Use after modifying a cron job so the app reflects the current state.",
+    parameters: Type.Object({
+      routine_id: Type.String({ description: "UUID of the routine to update (required)" }),
+      openclaw_cron_id: Type.Optional(Type.String({ description: "Updated cron job ID" })),
+      name: Type.Optional(Type.String({ description: "Updated routine name" })),
+      cron_expression: Type.Optional(Type.String({ description: "Updated cron expression" })),
+      schedule_human: Type.Optional(Type.String({ description: "Human readable schedule" })),
+      instruction: Type.Optional(Type.String({ description: "Updated task instructions" })),
+      timezone: Type.Optional(Type.String({ description: "Timezone string" })),
+      next_run_at: Type.Optional(Type.String({ description: "ISO timestamp of next run" })),
+      description: Type.Optional(Type.String({ description: "Updated description" })),
+      status: Type.Optional(Type.String({ description: "active, paused, or disabled" })),
+    }),
+    async execute(_id: string, params: any) {
+      const result = await wsSendOrHttp(
+        { type: "routine_update", ...params },
+        "POST", "routine-update", params,
+      );
+      return result?.ok
+        ? toolOk("Routine updated in app", { result })
+        : toolFail("Failed to update routine", { result });
+    },
+  });
+}

package/src/tools/sync.ts

@@ -0,0 +1,36 @@
+import { Type } from "@sinclair/typebox";
+import { toolOk, toolFail, wsSendOrHttp } from "./helpers.js";
+
+export function registerSyncTools(api: any) {
+  api.registerTool({
+    name: "clawaxis_confirm_doc_sync",
+    description: "Confirm that a document uploaded through the ClawAxis app has been received and processed.",
+    parameters: Type.Object({
+      document_id: Type.String({ description: "UUID of the document" }),
+      agent_skill_path: Type.Optional(Type.String({ description: "Path where the document was saved in agent skills" })),
+    }),
+    async execute(_id: string, params: any) {
+      const result = await wsSendOrHttp(
+        { type: "doc_synced", ...params },
+        "POST", "doc-synced", params,
+      );
+      return result ? toolOk("Document sync confirmed", { result }) : toolFail("Failed to confirm document sync");
+    },
+  });
+
+  api.registerTool({
+    name: "clawaxis_confirm_routine_sync",
+    description: "Confirm that a routine/cron job created through the ClawAxis app has been set up in OpenClaw.",
+    parameters: Type.Object({
+      routine_id: Type.String({ description: "UUID of the routine" }),
+      openclaw_cron_id: Type.Optional(Type.String({ description: "OpenClaw cron job ID that was created" })),
+    }),
+    async execute(_id: string, params: any) {
+      const result = await wsSendOrHttp(
+        { type: "routine_synced", ...params },
+        "POST", "routine-synced", params,
+      );
+      return result ? toolOk("Routine sync confirmed", { result }) : toolFail("Failed to confirm routine sync");
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+export interface GovernanceConfig {
+  imageTools: string[];
+  contentTools: string[];
+  publishingTools: string[];
+  memorySearch: {
+    contentQuery: string;
+    imageQuery: string;
+    maxResults: number;
+    minScore: number;
+    cacheDurationMs: number;
+  };
+  validation: {
+    requireCTA: boolean;
+    requirePermanentImages: boolean;
+    requireValidAuthor: boolean;
+    allowedContentTypes: string[];
+  };
+  logging: {
+    enabled: boolean;
+    logAllTools: boolean;
+    logGovernanceIssues: boolean;
+    debounceMs: number;
+  };
+}
+
+export interface ValidationIssue {
+  field: string;
+  issue: string;
+  severity: "error" | "warning";
+  autofix?: () => void;
+}
+
+export interface MemoryCacheEntry {
+  snippets: any[];
+  timestamp: number;
+}
+
+export interface HookContext {
+  toolName: string;
+  params?: Record<string, any>;
+  agentId?: string;
+  sessionKey?: string;
+  durationMs?: number;
+  success?: boolean;
+  error?: Error;
+  systemPrompt?: string;
+  api?: any;
+  _injectedDocs?: string;
+}
+
+export interface LogEntry {
+  action: string;
+  detail: string;
+  level: string;
+  metadata?: Record<string, any>;
+}
+
+export interface ClawAxisConfig {
+  relayUrl: string;
+  agentToken: string;
+  mediaDomain: string | null;
+  agentName: string | null;
+  governance: GovernanceConfig;
+}

package/src/utils.ts

@@ -0,0 +1,161 @@
+import WS from "ws";
+import { LOG_PREFIX, ANON_KEY } from "./config.js";
+import {
+  getRuntime,
+  getWs,
+  getIsAuthenticated,
+  getLogQueue,
+  getFlushTimeout,
+  setFlushTimeout,
+} from "./runtime.js";
+import type { ClawAxisConfig } from "./types.js";
+
+let _config: ClawAxisConfig | null = null;
+
+export function setUtilsConfig(cfg: ClawAxisConfig) {
+  _config = cfg;
+}
+
+function getRelayUrl(): string {
+  return _config?.relayUrl ?? "";
+}
+
+function getAgentToken(): string {
+  return _config?.agentToken ?? "";
+}
+
+function getGovernance() {
+  return _config?.governance;
+}
+
+export async function relayFetch(method: string, path: string, body?: any) {
+  const base = getRelayUrl();
+  const url = path ? `${base}/${path}` : base;
+  const opts: RequestInit = {
+    method,
+    headers: {
+      "Authorization": `Bearer ${ANON_KEY}`,
+      "apikey": ANON_KEY,
+      "x-agent-token": getAgentToken(),
+      "Content-Type": "application/json",
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+
+  try {
+    const res = await fetch(url, opts);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+
+      if (res.status === 401) {
+        console.error(`${LOG_PREFIX} Relay ${method} ${path || ""}: 401 Unauthorized — check agentToken`);
+      } else if (res.status === 429) {
+        const retryAfter = res.headers.get("retry-after");
+        console.warn(`${LOG_PREFIX} Relay ${method} ${path || ""}: 429 Rate limited${retryAfter ? ` (retry-after: ${retryAfter}s)` : ""}`);
+      } else if (res.status >= 500) {
+        console.error(`${LOG_PREFIX} Relay ${method} ${path || ""}: ${res.status} Server error — ${text.substring(0, 200)}`);
+      } else {
+        console.error(`${LOG_PREFIX} Relay ${method} ${path || ""} failed: ${res.status}`);
+      }
+
+      return null;
+    }
+    return await res.json();
+  } catch (err: any) {
+    console.error(`${LOG_PREFIX} Relay ${method} ${path || ""} error:`, err.message);
+    return null;
+  }
+}
+
+export async function relayLog(
+  action: string,
+  detail: string,
+  level: "info" | "success" | "warning" | "error" = "info",
+  metadata?: Record<string, any>
+): Promise<void> {
+  const governance = getGovernance();
+  if (!governance?.logging.enabled) return;
+
+  const logQueue = getLogQueue();
+  logQueue.push({ action, detail, level, metadata: metadata || {} });
+
+  const existing = getFlushTimeout();
+  if (existing) clearTimeout(existing);
+
+  setFlushTimeout(setTimeout(async () => {
+    await flushLogQueue();
+  }, governance.logging.debounceMs));
+}
+
+export async function flushLogQueue(): Promise<void> {
+  const logQueue = getLogQueue();
+  if (logQueue.length === 0) return;
+
+  const batch = [...logQueue];
+  logQueue.length = 0;
+
+  const ws = getWs();
+  if (ws?.readyState === WS.OPEN && getIsAuthenticated()) {
+    const entries = batch.map(log => {
+      const { tokens_used, cost, duration_ms, ...extraMetadata } = log.metadata || {};
+      return {
+        action: log.action,
+        detail: log.detail,
+        level: log.level || "info",
+        timestamp: new Date().toISOString(),
+        tokens_used: tokens_used || 0,
+        cost: cost || 0,
+        duration_ms: duration_ms || null,
+        metadata: Object.keys(extraMetadata).length > 0 ? extraMetadata : undefined,
+      };
+    });
+
+    (ws as any).send(JSON.stringify({
+      type: "log",
+      entries: entries.slice(0, 10)
+    }));
+  } else {
+    for (const log of batch) {
+      try {
+        await relayFetch("POST", "log", log);
+      } catch (err) {
+        console.error(`${LOG_PREFIX} Failed to log:`, log.action, err);
+      }
+    }
+  }
+}
+
+export function getModelName(): string {
+  const runtime = getRuntime();
+  try {
+    const agentModel = runtime?.config?.agents?.defaults?.model;
+    if (agentModel) return agentModel;
+
+    const providerModel = runtime?.config?.models?.default;
+    if (providerModel) return providerModel;
+
+    const sessionModel = runtime?.session?.store?.model;
+    if (sessionModel) return sessionModel;
+
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export function getSessionTokens(runtime: any): number {
+  try {
+    const store = runtime?.session?.store;
+    if (store?.totalTokens) return store.totalTokens;
+
+    const stats = runtime?.session?.stats;
+    if (stats?.tokens?.total) return stats.tokens.total;
+    if (stats?.totalTokens) return stats.totalTokens;
+
+    if (store?.contextTokens) return store.contextTokens;
+
+    return 0;
+  } catch {
+    return 0;
+  }
+}

package/src/websocket.ts

@@ -0,0 +1,294 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import WS from "ws";
+import {
+  LOG_PREFIX,
+  PLUGIN_VERSION,
+  HEARTBEAT_MS,
+  PING_MS,
+  REAUTH_BUFFER_MS,
+  MAX_RECONNECT_DELAY,
+} from "./config.js";
+import {
+  getRuntime,
+  getWs,
+  setWs,
+  getIsAuthenticated,
+  setIsAuthenticated,
+  getAuthenticatedAgentId,
+  setAuthenticatedAgentId,
+  getReconnectAttempts,
+  setReconnectAttempts,
+  incrementReconnectAttempts,
+  getPingInterval,
+  setPingInterval,
+  getHeartbeatInterval,
+  setHeartbeatInterval,
+  isRunning,
+  setRunning,
+  getSessionTokensAccumulated,
+  getSessionCostAccumulated,
+  getLastHeartbeatTokens,
+  setLastHeartbeatTokens,
+  getFlushTimeout,
+  setFlushTimeout,
+} from "./runtime.js";
+import { relayLog, flushLogQueue, getModelName } from "./utils.js";
+import { handleMessage, handleCommand } from "./message-handler.js";
+import { processPendingDocs, processDocDeletion } from "./sync/documents.js";
+import { processPendingRoutines } from "./sync/routines.js";
+import type { ClawAxisConfig } from "./types.js";
+
+let _config: ClawAxisConfig | null = null;
+
+function getAgentToken(): string {
+  return _config?.agentToken ?? "";
+}
+
+function getRelayUrl(): string {
+  return _config?.relayUrl ?? "";
+}
+
+function sendAuth() {
+  const ws = getWs();
+  if (!ws || ws.readyState !== WS.OPEN) return;
+
+  const authMsg = {
+    type: "auth",
+    token: getAgentToken(),
+    plugin_version: PLUGIN_VERSION,
+    openclaw_version: getRuntime()?.version || "unknown",
+    host_os: process.platform
+  };
+
+  console.log(`${LOG_PREFIX} Sending auth...`);
+  ws.send(JSON.stringify(authMsg));
+}
+
+function cleanup() {
+  setIsAuthenticated(false);
+  setAuthenticatedAgentId(null);
+
+  const ping = getPingInterval();
+  if (ping) {
+    clearInterval(ping);
+    setPingInterval(null);
+  }
+}
+
+function startKeepalive() {
+  const existing = getPingInterval();
+  if (existing) clearInterval(existing);
+
+  setPingInterval(setInterval(() => {
+    const ws = getWs();
+    if (ws?.readyState === WS.OPEN && getIsAuthenticated()) {
+      ws.send(JSON.stringify({ type: "ping" }));
+    }
+  }, PING_MS));
+}
+
+function startHeartbeat() {
+  const existing = getHeartbeatInterval();
+  if (existing) clearInterval(existing);
+
+  setHeartbeatInterval(setInterval(async () => {
+    const ws = getWs();
+    if (ws?.readyState === WS.OPEN && getIsAuthenticated()) {
+      const uptime = process.uptime();
+      const sessionTokens = getSessionTokensAccumulated();
+      const tokensDelta = sessionTokens - getLastHeartbeatTokens();
+
+      ws.send(JSON.stringify({
+        type: "heartbeat",
+        status: "online",
+        model: getModelName(),
+        openclaw_version: getRuntime()?.version || "unknown",
+        uptime_seconds: Math.floor(uptime),
+        tokens_used_session: sessionTokens,
+        cost_session: getSessionCostAccumulated(),
+        tokens_delta: tokensDelta > 0 ? tokensDelta : 0,
+      }));
+
+      setLastHeartbeatTokens(sessionTokens);
+    }
+  }, HEARTBEAT_MS));
+}
+
+function scheduleReconnect() {
+  if (!isRunning()) return;
+
+  const base = Math.min(1000 * Math.pow(2, getReconnectAttempts()), MAX_RECONNECT_DELAY);
+  const jitter = base * 0.3 * (Math.random() * 2 - 1);
+  const delay = Math.max(0, Math.round(base + jitter));
+  incrementReconnectAttempts();
+
+  console.log(`${LOG_PREFIX} Reconnecting in ${delay}ms (attempt ${getReconnectAttempts()})...`);
+
+  setTimeout(() => {
+    if (isRunning()) connectWebSocket();
+  }, delay);
+}
+
+// ─── WebSocket message router ────────────────────────────
+
+async function handleWebSocketMessage(msg: any) {
+  console.log(`${LOG_PREFIX} [WS] Received: ${msg.type}`);
+
+  switch (msg.type) {
+    case "auth_ok":
+      await handleAuthOk(msg);
+      break;
+    case "auth_error":
+      await handleAuthError(msg);
+      break;
+    case "message":
+      await handleMessage(msg);
+      break;
+    case "command":
+      await handleCommand(msg);
+      break;
+    case "sync":
+    case "heartbeat_ack":
+      await handleSync(msg);
+      break;
+    case "content_ack":
+      console.log(`${LOG_PREFIX} Content ${msg.action}: ${msg.content_id}`);
+      break;
+    case "doc_deleted":
+      await processDocDeletion(msg);
+      break;
+    case "routine_ack":
+      console.log(`${LOG_PREFIX} Routine ${msg.action}: ${msg.routine_id}`);
+      break;
+    case "error":
+      console.warn(`${LOG_PREFIX} Server error: ${msg.reason} \u2014 ${msg.detail || ""}`);
+      break;
+    case "reauth":
+      await handleReauth(msg);
+      break;
+    case "pong":
+      break;
+    default:
+      console.warn(`${LOG_PREFIX} Unknown message type: ${msg.type}`);
+  }
+}
+
+async function handleAuthOk(msg: any) {
+  console.log(`${LOG_PREFIX} \u2713 Authenticated`);
+  setIsAuthenticated(true);
+  setAuthenticatedAgentId(msg.agent_id || null);
+  if (msg.agent_id) console.log(`${LOG_PREFIX} Agent ID: ${msg.agent_id}`);
+  startKeepalive();
+}
+
+async function handleAuthError(msg: any) {
+  console.error(`${LOG_PREFIX} \u274C Auth failed: ${msg.reason}`);
+  setIsAuthenticated(false);
+  setRunning(false);
+  getWs()?.close();
+  await relayLog("error", `Authentication failed: ${msg.reason}`, "error", { reason: msg.reason });
+}
+
+async function handleSync(msg: any) {
+  console.log(`${LOG_PREFIX} Sync received: ${msg.pending_docs?.length || 0} docs, ${msg.pending_routines?.length || 0} routines`);
+  if (msg.pending_docs?.length > 0) await processPendingDocs(msg.pending_docs);
+  if (msg.pending_routines?.length > 0) await processPendingRoutines(msg.pending_routines);
+}
+
+async function handleReauth(msg: any) {
+  console.log(`${LOG_PREFIX} Re-auth requested (deadline: ${msg.deadline_ms}ms)`);
+  setTimeout(() => {
+    const ws = getWs();
+    if (ws?.readyState === WS.OPEN) sendAuth();
+  }, Math.max(100, msg.deadline_ms - REAUTH_BUFFER_MS));
+}
+
+// ─── Connection ──────────────────────────────────────────
+
+function connectWebSocket() {
+  const wsUrl = getRelayUrl().replace(/^https?:/, "wss:").replace(/\/agent-relay$/, "/ws-relay");
+
+  console.log(`${LOG_PREFIX} [WS] Connecting to: ${wsUrl}`);
+
+  try {
+    const socket = new WS(wsUrl);
+    setWs(socket as any);
+
+    socket.on("open", () => {
+      console.log(`${LOG_PREFIX} [WS] \u2713 Connection opened`);
+      setReconnectAttempts(0);
+      sendAuth();
+    });
+
+    socket.on("message", async (data: WS.RawData) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        await handleWebSocketMessage(msg);
+      } catch (err) {
+        console.error(`${LOG_PREFIX} [WS] Failed to parse message:`, err);
+      }
+    });
+
+    socket.on("close", (code: number, reason: Buffer) => {
+      console.log(`${LOG_PREFIX} [WS] Closed (code ${code}, reason: ${reason.toString() || "none"}), reconnecting...`);
+      cleanup();
+      scheduleReconnect();
+    });
+
+    socket.on("error", (err: Error) => {
+      console.error(`${LOG_PREFIX} [WS] Socket error:`, err.message);
+    });
+
+  } catch (err: any) {
+    console.error(`${LOG_PREFIX} [WS] Failed to create WebSocket:`, err.message);
+    scheduleReconnect();
+  }
+}
+
+// ─── Service factory ─────────────────────────────────────
+
+export function createWebSocketService(cfg: ClawAxisConfig) {
+  _config = cfg;
+  let started = false;
+
+  return {
+    id: "clawaxis-ws",
+
+    async start() {
+      if (started) return;
+      started = true;
+      console.log(`${LOG_PREFIX} \uD83C\uDF10 Starting WebSocket connection...`);
+      setRunning(true);
+      connectWebSocket();
+      startHeartbeat();
+    },
+
+    async stop() {
+      console.log(`${LOG_PREFIX} Shutting down WebSocket...`);
+      started = false;
+      setRunning(false);
+
+      const ws = getWs();
+      if (ws?.readyState === WS.OPEN && getIsAuthenticated()) {
+        (ws as any).send(JSON.stringify({ type: "heartbeat", status: "offline" }));
+        await sleep(100);
+      }
+
+      const ft = getFlushTimeout();
+      if (ft) {
+        clearTimeout(ft);
+        setFlushTimeout(null);
+        await flushLogQueue();
+      }
+
+      const hb = getHeartbeatInterval();
+      if (hb) {
+        clearInterval(hb);
+        setHeartbeatInterval(null);
+      }
+
+      cleanup();
+      (ws as any)?.close();
+    },
+  };
+}