clawaxis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawAxis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,441 @@
+# ClawAxis Plugin for OpenClaw
+
+**Version:** 1.0.0  
+**License:** MIT  
+**Status:** Production Ready
+
+Official OpenClaw channel plugin for ClawAxis - enables real-time communication between your OpenClaw agent and the ClawAxis iOS app.
+
+---
+
+## Features
+
+### Real-Time WebSocket Communication
+- Persistent WebSocket connection to ClawAxis relay (Supabase)
+- Automatic reconnection with exponential backoff
+- Bidirectional messaging (user <-> agent)
+- Message status updates ("processing", "complete", "error")
+- Keepalive pings + periodic heartbeats
+
+### Three-Layer Governance System
+
+**Layer 1: Activity Logging**
+- Real-time visibility into agent operations
+- Batched relay calls (debounced, max 10/batch)
+- Tool execution tracking with duration/tokens/cost
+- Error and warning collection
+
+**Layer 2: Style Injection**
+- Automatic brand guideline enforcement
+- Memory-based style doc search (cached 5 minutes)
+- Content-aware injection (blog/social/image tools)
+- Zero manual prompt engineering required
+
+**Layer 3: Content Validation**
+- Pre-publish quality checks (CTA, image domains, attribution)
+- Auto-fix for common issues
+- Blocking errors vs non-blocking warnings
+- Permanent image URL enforcement (R2/S3/B2)
+
+### 10 Registered Tools
+
+| Tool | Purpose |
+|------|---------|
+| `clawaxis_post_content` | Post content for review (blog, social, website, email, ad) |
+| `clawaxis_update_content` | Edit existing content by ID |
+| `clawaxis_get_content` | Retrieve content list or specific item |
+| `clawaxis_post_log` | Manual activity logging |
+| `clawaxis_confirm_doc_sync` | Confirm document upload received |
+| `clawaxis_confirm_routine_sync` | Confirm cron job created |
+| `clawaxis_notify_routine` | Register new routine/cron in app |
+| `clawaxis_update_routine` | Update existing routine in app |
+| `clawaxis_upload_media` | Upload image to R2 (permanent storage) |
+| `clawaxis_memory_search` | Search ClawAxis governed memory (pgvector) |
+
+### Document Sync
+- Automatic document downloads from ClawAxis app
+- Writes to `workspace/memory/docs/{category}/` (auto-indexed by OpenClaw)
+- Agent notification on upload (with confirmation tool)
+- Update detection (version tracking)
+- Deletion handling (file cleanup + agent notification)
+
+### Routine/Cron Sync
+- Collaborative model: agent owns cron execution
+- App requests routine -> Agent creates cron -> Confirmation loop
+- Update support (modify existing routines)
+- Full cron expression + human-readable schedule
+
+---
+
+## Installation
+
+### 1. Install Plugin
+
+```bash
+mkdir -p ~/.openclaw/extensions/clawaxis-plugin
+cd ~/.openclaw/extensions/clawaxis-plugin
+
+# Download plugin files
+git clone https://github.com/vdiscobot/clawaxis-plugin.git .
+
+# Install dependencies (optional - OpenClaw resolves npm modules automatically)
+npm install
+```
+
+### 2. Configure OpenClaw
+
+Add to `~/.openclaw/openclaw.json`. The primary config location is `channels.clawaxis`:
+
+```json
+{
+  "channels": {
+    "clawaxis": {
+      "relayUrl": "https://fqwpwypyzcbmdeajlkzt.supabase.co/functions/v1/ws-relay",
+      "agentToken": "oc_tk_YOUR_AGENT_TOKEN_HERE",
+      "mediaDomain": "pub-YOUR_R2_BUCKET.r2.dev",
+      "agentName": "YourAgentName"
+    }
+  },
+  "bindings": [
+    {
+      "surface": "clawaxis",
+      "channel": "clawaxis",
+      "agent": "main",
+      "enabled": true
+    }
+  ]
+}
+```
+
+> **Backward compatibility:** The plugin also reads from `plugins.entries.clawaxis-plugin.config` if `channels.clawaxis` is not present.
+
+**Required fields:**
+- `relayUrl` - ClawAxis WebSocket relay endpoint
+- `agentToken` - Your unique agent authentication token (get from ClawAxis app)
+
+**Optional fields:**
+- `mediaDomain` - Your R2/S3/B2 bucket domain for permanent image storage
+- `agentName` - Agent's name (for author attribution validation)
+
+### 3. Optional: Configure Governance
+
+Add governance settings inside the channel config:
+
+```json
+{
+  "channels": {
+    "clawaxis": {
+      "relayUrl": "...",
+      "agentToken": "...",
+      "governance": {
+        "imageTools": ["generate_image", "dall_e", "stability"],
+        "validation": {
+          "requireCTA": true,
+          "requirePermanentImages": true,
+          "requireValidAuthor": true
+        },
+        "logging": {
+          "enabled": true,
+          "logAllTools": false
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+Check logs for successful connection:
+
+```bash
+tail -f ~/.openclaw/logs/gateway.log | grep 🦞
+```
+
+Expected output:
+```
+🦞 ==========================================
+🦞 🦞 ClawAxis Plugin (WebSocket)
+🦞 ==========================================
+🦞 ✓ Config loaded
+🦞 ✓ Channel 'clawaxis' registered
+🦞 🛡️  Registering governance hooks...
+🦞 ✓ Governance hooks registered (2 hooks)
+🦞 ✅ All 10 tools registered successfully
+🦞 ✓ WebSocket service registered
+🦞 ✓ ClawAxis plugin loaded (WebSocket mode)
+```
+
+---
+
+## Configuration Reference
+
+### Core Settings
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `relayUrl` | string | Yes | ClawAxis relay endpoint (WebSocket or HTTPS) |
+| `agentToken` | string | Yes | Agent authentication token |
+| `mediaDomain` | string | No | R2/S3/B2 bucket domain for permanent images |
+| `agentName` | string | No | Agent name (used for author validation) |
+
+### Governance Settings
+
+#### `governance.imageTools`
+Array of tool name patterns to detect image generation tools.
+
+**Example:**
+```json
+["generate_image", "dall_e", "stability", "midjourney", "flux"]
+```
+
+#### `governance.validation`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `requireCTA` | boolean | `false` | Require call-to-action in blog/website content |
+| `requirePermanentImages` | boolean | `false` | Block content with non-permanent image URLs |
+| `requireValidAuthor` | boolean | `false` | Block content with agent self-attribution |
+| `allowedContentTypes` | string[] | See below | Valid content_type values |
+
+**Default allowed content types:**
+```json
+["twitter", "instagram", "linkedin", "facebook", "tiktok", "youtube",
+ "blog", "report", "email", "ad", "website", "document", "other"]
+```
+
+#### `governance.logging`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable activity logging |
+| `logAllTools` | boolean | `false` | Log all tools (not just clawaxis/governance tools) |
+| `logGovernanceIssues` | boolean | `true` | Log validation warnings/errors |
+| `debounceMs` | number | `100` | Batch log flush delay (milliseconds) |
+
+#### `governance.memorySearch`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `contentQuery` | string | `"{content_type} style guide writing tone brand voice"` | Memory search query for content tools |
+| `imageQuery` | string | `"image style guide brand visual aesthetic colors"` | Memory search query for image tools |
+| `maxResults` | number | `5` | Max memory chunks to inject |
+| `minScore` | number | `0.65` | Minimum similarity score (0.0-1.0) |
+| `cacheDurationMs` | number | `300000` | Cache duration (5 minutes) |
+
+---
+
+## Architecture
+
+### File Structure
+
+```
+clawaxis-plugin/
+  openclaw.plugin.json        # Plugin manifest (id, configSchema, uiHints)
+  package.json                # @clawaxis/plugin
+  index.ts                    # Thin entry point (~40 lines)
+  CLAWAXIS.md                 # Agent instruction manual (untouched)
+  src/
+    types.ts                  # All TypeScript interfaces
+    runtime.ts                # Centralized global state (getters/setters)
+    config.ts                 # Config loading, defaults, constants
+    utils.ts                  # relayFetch, relayLog, flushLogQueue, helpers
+    channel.ts                # Channel definition + outbound methods
+    websocket.ts              # WebSocket service (api.registerService lifecycle)
+    message-handler.ts        # Inbound message dispatch + dispatchSystemMessage
+    tools/
+      index.ts                # Barrel - registerTools()
+      content.ts              # post_content, update_content, get_content
+      logging.ts              # post_log
+      sync.ts                 # confirm_doc_sync, confirm_routine_sync
+      routines.ts             # notify_routine, update_routine
+      media.ts                # upload_media
+      memory.ts               # memory_search
+    governance/
+      hooks.ts                # registerGovernanceHooks() (before/after_tool_call)
+      logging.ts              # Layer 1: logToolCall()
+      style-injection.ts      # Layer 2: searchMemory() + injectStyleDocs()
+      validation.ts           # Layer 3: validateContent() + enforceGovernance()
+    sync/
+      documents.ts            # processPendingDocs, processDocDeletion, resolveDocPath
+      routines.ts             # processPendingRoutines
+```
+
+### Key Architectural Decisions
+
+- **WebSocket lifecycle** is managed by `api.registerService()` instead of manual signal handlers. OpenClaw handles `start()` and `stop()` calls.
+- **Global state** lives in `src/runtime.ts` behind getter/setter functions. No module imports scattered mutable `let` variables.
+- **Internal API isolation**: The `dispatchReplyWithBufferedBlockDispatcher` call is centralized in `dispatchSystemMessage()` in `src/message-handler.ts`. All sync code (docs, routines) uses this helper.
+- **Config hierarchy**: Primary location is `channels.clawaxis`, fallback to `plugins.entries.clawaxis-plugin.config` for backward compatibility.
+
+### WebSocket Protocol
+
+**Message Types (Plugin -> Relay):**
+- `auth` - Initial authentication
+- `ping` - Keepalive (30s)
+- `heartbeat` - Status report (60s)
+- `reply` - Agent response
+- `log` - Activity logging (batched)
+- `content` - New/updated content
+- `doc_synced` - Document sync confirmation
+- `routine_synced` - Routine sync confirmation
+
+**Message Types (Relay -> Plugin):**
+- `auth_ok` - Authentication success (includes `agent_id`)
+- `auth_error` - Authentication failure
+- `pong` - Keepalive response
+- `heartbeat_ack` - Heartbeat acknowledged + pending sync data
+- `message` - User message to process
+- `command` - System command (future use)
+- `sync` - Pending documents/routines
+- `doc_deleted` - Document deleted by user
+- `content_ack` - Content received/processed
+- `routine_ack` - Routine received/processed
+- `reauth` - Token expiring (re-auth deadline)
+- `error` - Server error
+
+### Session Isolation
+
+Each authenticated agent gets a unique session key:
+
+```
+agent:main:clawaxis:{agent_id}
+```
+
+Multiple ClawAxis agents (iOS app, dashboard, future installs) can share one OpenClaw gateway without session file lock contention.
+
+### Governance Hook Execution
+
+**`before_tool_call` (3 layers):**
+1. **Activity Logging** - Log tool start
+2. **Style Injection** - Search memory for brand docs, inject into tool params
+3. **Content Validation** - Check content against governance rules, auto-fix or block
+
+**`after_tool_call` (1 layer):**
+1. **Activity Logging** - Log tool completion (duration, tokens, success/error)
+2. **Flush Logs** - Send batched logs to relay
+
+### Document Sync Flow
+
+1. **User uploads document in ClawAxis app**
+2. **App stores in Supabase database** (`documents` table)
+3. **Next heartbeat_ack includes `pending_docs`**
+4. **Plugin downloads and writes to workspace:**
+   ```
+   ~/.openclaw/workspace/memory/docs/{category}/{slug}.md
+   ```
+5. **OpenClaw auto-indexes file** (searchable via `memory_search`)
+6. **Plugin notifies agent via system message**
+7. **Agent confirms sync with `clawaxis_confirm_doc_sync`**
+
+### Routine Sync Flow
+
+1. **User creates routine in ClawAxis app**
+2. **App stores in database** (`routines` table)
+3. **Next heartbeat_ack includes `pending_routines`**
+4. **Plugin dispatches routine request to agent**
+5. **Agent creates OpenClaw cron job**
+6. **Agent calls `clawaxis_notify_routine` with cron ID**
+7. **App links routine to cron job**
+
+---
+
+## Security Model
+
+### Authentication Layers
+
+**Layer 1: Supabase Anon Key (Public)**
+- Hardcoded in plugin source
+- Allows connection to Supabase
+- **No data access without additional auth**
+
+**Layer 2: Agent Token (Secret)**
+- Unique per user/agent
+- Format: `oc_tk_{64_hex_chars}`
+- Stored in OpenClaw config (encrypted)
+- Sent in `x-agent-token` header + WebSocket auth
+
+**Layer 3: Row Level Security (RLS)**
+- Backend validates agent token belongs to user
+- User can only access their own data
+- Zero-trust: even with anon key, RLS blocks unauthorized access
+
+---
+
+## Development
+
+### Testing Locally
+
+1. **Edit plugin code** in the `src/` modules
+2. **Restart gateway:**
+   ```bash
+   openclaw gateway stop
+   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
+   ```
+3. **Watch logs:**
+   ```bash
+   tail -f ~/.openclaw/logs/gateway.log
+   ```
+
+### Common Issues
+
+**Issue:** Plugin not loading  
+**Fix:** Check `openclaw gateway status` - plugin must show `ON | OK`
+
+**Issue:** WebSocket disconnects every 10s  
+**Fix:** Check relay URL is correct (must be `ws-relay`, not `agent-relay`)
+
+**Issue:** Agent doesn't see tools  
+**Fix:** Restart gateway (SIGUSR1 isn't enough for plugin changes)
+
+**Issue:** Document sync doesn't trigger  
+**Fix:** Wait for next heartbeat (60s) or force reconnect
+
+---
+
+## Changelog
+
+### v1.0.0 (2026-02-18)
+- Modular architecture: 2066-line monolith split into 20 focused modules
+- Plugin manifest (`openclaw.plugin.json`) with configSchema and uiHints
+- WebSocket lifecycle managed via `api.registerService()`
+- Centralized runtime state with getter/setter pattern
+- `dispatchSystemMessage()` helper isolates internal API usage
+- Config reads from `channels.clawaxis` (primary) with backward compat
+
+### v0.1.0 (2026-02-18)
+- Initial production release
+- WebSocket real-time communication
+- 10 tools registered
+- 3-layer governance system
+- Document sync with auto-indexing
+- Routine/cron collaboration
+- Session isolation (multi-agent support)
+- ClawAxis Memory Search (Tool 10)
+- Message status updates
+- Document deletion handling
+
+---
+
+## Links
+
+- **GitHub:** https://github.com/vdiscobot/clawaxis-plugin
+- **Documentation:** [CLAWAXIS.md](./CLAWAXIS.md)
+- **ClawAxis iOS App:** (Coming soon)
+- **OpenClaw:** https://openclaw.ai
+- **OpenClaw Docs:** https://docs.openclaw.ai
+
+---
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+---
+
+**Built with love by the ClawAxis team**  
+**Powered by OpenClaw**

package/index.ts

@@ -0,0 +1,53 @@
+import { LOG_PREFIX, PLUGIN_VERSION, loadConfig } from "./src/config.js";
+import { setRuntime } from "./src/runtime.js";
+import { setUtilsConfig } from "./src/utils.js";
+import { clawaxisChannel } from "./src/channel.js";
+import { registerGovernanceHooks } from "./src/governance/hooks.js";
+import { registerTools } from "./src/tools/index.js";
+
+function register(api: any) {
+  console.log(`${LOG_PREFIX} ==========================================`);
+  console.log(`${LOG_PREFIX} \uD83E\uDD9E ClawAxis Plugin v${PLUGIN_VERSION}`);
+  console.log(`${LOG_PREFIX} ==========================================`);
+
+  setRuntime(api.runtime);
+
+  const config = loadConfig(api.config);
+  if (!config) {
+    console.warn(`${LOG_PREFIX} No channels.clawaxis config found (or missing relayUrl/agentToken). Plugin disabled.`);
+    return;
+  }
+
+  setUtilsConfig(config);
+
+  console.log(`${LOG_PREFIX} \u2713 Config loaded`);
+  if (config.mediaDomain) console.log(`${LOG_PREFIX}   \u2022 Media domain: ${config.mediaDomain}`);
+  if (config.agentName) console.log(`${LOG_PREFIX}   \u2022 Agent name: ${config.agentName}`);
+
+  if (typeof api.registerChannel === "function") {
+    api.registerChannel({ plugin: clawaxisChannel });
+    console.log(`${LOG_PREFIX} \u2713 Channel 'clawaxis' registered (WebSocket starts via gateway.startAccount)`);
+  } else {
+    console.warn(`${LOG_PREFIX} api.registerChannel not available — channel not registered`);
+  }
+
+  registerGovernanceHooks(api, config);
+
+  if (typeof api.registerTool === "function") {
+    registerTools(api, config.agentToken);
+    console.log(`${LOG_PREFIX} \u2705 All 10 tools registered successfully`);
+  } else {
+    console.warn(`${LOG_PREFIX} api.registerTool not available — tools not registered`);
+  }
+
+  console.log(`${LOG_PREFIX} ==========================================`);
+  console.log(`${LOG_PREFIX} \u2713 ClawAxis plugin loaded`);
+  console.log(`${LOG_PREFIX} ==========================================`);
+}
+
+export default {
+  id: "clawaxis",
+  name: "ClawAxis",
+  version: PLUGIN_VERSION,
+  register,
+};

package/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "id": "clawaxis",
+  "name": "ClawAxis",
+  "version": "1.0.0",
+  "description": "Real-time bridge between OpenClaw agents and the ClawAxis iOS app. Channel plugin with governance, content management, and document/routine sync.",
+  "channels": ["clawaxis"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "relayUrl": {
+        "type": "string",
+        "description": "ClawAxis WebSocket relay endpoint URL"
+      },
+      "agentToken": {
+        "type": "string",
+        "description": "Agent authentication token (oc_tk_...)"
+      },
+      "mediaDomain": {
+        "type": "string",
+        "description": "R2/S3 bucket domain for permanent image storage"
+      },
+      "agentName": {
+        "type": "string",
+        "description": "Agent name for author attribution validation"
+      },
+      "governance": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "imageTools": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Tool name patterns to detect image generation tools"
+          },
+          "contentTools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "publishingTools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "memorySearch": {
+            "type": "object",
+            "properties": {
+              "contentQuery": { "type": "string" },
+              "imageQuery": { "type": "string" },
+              "maxResults": { "type": "number" },
+              "minScore": { "type": "number" },
+              "cacheDurationMs": { "type": "number" }
+            }
+          },
+          "validation": {
+            "type": "object",
+            "properties": {
+              "requireCTA": { "type": "boolean" },
+              "requirePermanentImages": { "type": "boolean" },
+              "requireValidAuthor": { "type": "boolean" },
+              "allowedContentTypes": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          },
+          "logging": {
+            "type": "object",
+            "properties": {
+              "enabled": { "type": "boolean" },
+              "logAllTools": { "type": "boolean" },
+              "logGovernanceIssues": { "type": "boolean" },
+              "debounceMs": { "type": "number" }
+            }
+          }
+        }
+      }
+    },
+    "required": ["relayUrl", "agentToken"]
+  },
+  "uiHints": {
+    "relayUrl": { "label": "Relay URL", "placeholder": "https://your-relay.supabase.co/functions/v1/ws-relay" },
+    "agentToken": { "label": "Agent Token", "sensitive": true, "placeholder": "oc_tk_..." },
+    "mediaDomain": { "label": "Media Domain", "placeholder": "pub-xxxxx.r2.dev" },
+    "agentName": { "label": "Agent Name" }
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "clawaxis",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "CLAWAXIS.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "clawaxis",
+    "websocket",
+    "mobile",
+    "channel"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "clawaxis",
+      "label": "ClawAxis",
+      "selectionLabel": "ClawAxis (Mobile)",
+      "blurb": "Control your OpenClaw agent from your phone."
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "ws": "^8.19.0"
+  }
+}