openclaw-face-hooks 0.0.1

package/HOOK.md

@@ -0,0 +1,50 @@
+---
+name: openclaw-face-hooks
+description: "Push agent busy/idle status to Cloudflare R2 on command events"
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📡",
+        "events": ["command:new", "command:stop", "command:reset"],
+        "requires": { "env": ["R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ENDPOINT", "R2_BUCKET"] },
+      },
+  }
+---
+
+# R2 Status Hook
+
+Pushes agent busy/idle status to Cloudflare R2 as `status.json` on command events. Designed for zero-port-exposure status visualization — a GitHub Pages dashboard polls R2 to display real-time agent state.
+
+## What It Does
+
+- On `/new` command → uploads `{ "busy": true, ... }` to R2
+- On `/stop` or `/reset` command → uploads `{ "busy": false, ... }` to R2
+- Upload failures are caught and logged — they never interrupt OpenClaw operation
+
+## Status JSON Schema
+
+```json
+{
+  "busy": true,
+  "ts": 1704067200000,
+  "sessionKey": "agent:main:main",
+  "source": "telegram"
+}
+```
+
+## Requirements
+
+- Cloudflare R2 bucket with public-read access
+- R2 API token with `PutObject` permission
+
+## Configuration
+
+Set environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `R2_ACCESS_KEY_ID` | R2 API Access Key ID |
+| `R2_SECRET_ACCESS_KEY` | R2 API Secret Access Key |
+| `R2_ENDPOINT` | R2 endpoint URL (e.g., `https://[account-id].r2.cloudflarestorage.com`) |
+| `R2_BUCKET` | Bucket name (e.g., `openclaw-status-alice`) |

package/__tests__/handler.test.ts

@@ -0,0 +1,141 @@
+/**
+ * R2 Status Hook - Handler Unit Tests
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock @aws-sdk/client-s3 before importing handler
+const mockSend = vi.fn().mockResolvedValue({});
+vi.mock('@aws-sdk/client-s3', () => ({
+  S3Client: vi.fn().mockImplementation(() => ({ send: mockSend })),
+  PutObjectCommand: vi.fn().mockImplementation((params) => params),
+}));
+
+import handler, { uploadStatus, StatusPayload } from '../handler';
+
+describe('handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    process.env.R2_BUCKET = 'test-bucket';
+    process.env.R2_ENDPOINT = 'https://test.r2.cloudflarestorage.com';
+    process.env.R2_ACCESS_KEY_ID = 'test-key';
+    process.env.R2_SECRET_ACCESS_KEY = 'test-secret';
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.R2_BUCKET;
+    delete process.env.R2_ENDPOINT;
+    delete process.env.R2_ACCESS_KEY_ID;
+    delete process.env.R2_SECRET_ACCESS_KEY;
+  });
+
+  function createEvent(action: string, type = 'command') {
+    return {
+      type,
+      action,
+      sessionKey: 'agent:main:main',
+      timestamp: new Date('2025-01-01T00:00:00Z'),
+      messages: [] as string[],
+      context: { commandSource: 'telegram' },
+    };
+  }
+
+  describe('event filtering', () => {
+    it('should handle command:new events', async () => {
+      await handler(createEvent('new'));
+      // Fire-and-forget, give it a tick
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSend).toHaveBeenCalled();
+    });
+
+    it('should handle command:stop events', async () => {
+      await handler(createEvent('stop'));
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSend).toHaveBeenCalled();
+    });
+
+    it('should handle command:reset events', async () => {
+      await handler(createEvent('reset'));
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSend).toHaveBeenCalled();
+    });
+
+    it('should ignore non-command events', async () => {
+      await handler(createEvent('bootstrap', 'agent'));
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSend).not.toHaveBeenCalled();
+    });
+
+    it('should ignore unknown command actions', async () => {
+      await handler(createEvent('unknown'));
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockSend).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('busy state mapping', () => {
+    it('command:new should set busy: true', async () => {
+      await handler(createEvent('new'));
+      await new Promise((r) => setTimeout(r, 10));
+
+      const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+      const call = vi.mocked(PutObjectCommand).mock.calls[0][0] as any;
+      const payload = JSON.parse(call.Body) as StatusPayload;
+      expect(payload.busy).toBe(true);
+    });
+
+    it('command:stop should set busy: false', async () => {
+      await handler(createEvent('stop'));
+      await new Promise((r) => setTimeout(r, 10));
+
+      const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+      const calls = vi.mocked(PutObjectCommand).mock.calls;
+      const call = calls[calls.length - 1][0] as any;
+      const payload = JSON.parse(call.Body) as StatusPayload;
+      expect(payload.busy).toBe(false);
+    });
+
+    it('command:reset should set busy: false', async () => {
+      await handler(createEvent('reset'));
+      await new Promise((r) => setTimeout(r, 10));
+
+      const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+      const calls = vi.mocked(PutObjectCommand).mock.calls;
+      const call = calls[calls.length - 1][0] as any;
+      const payload = JSON.parse(call.Body) as StatusPayload;
+      expect(payload.busy).toBe(false);
+    });
+  });
+
+  describe('payload structure', () => {
+    it('should include sessionKey and source from event', async () => {
+      await handler(createEvent('new'));
+      await new Promise((r) => setTimeout(r, 10));
+
+      const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+      const call = vi.mocked(PutObjectCommand).mock.calls[0][0] as any;
+      const payload = JSON.parse(call.Body) as StatusPayload;
+      expect(payload.sessionKey).toBe('agent:main:main');
+      expect(payload.source).toBe('telegram');
+      expect(typeof payload.ts).toBe('number');
+    });
+  });
+
+  describe('uploadStatus', () => {
+    it('should skip upload when R2_BUCKET is not set', async () => {
+      delete process.env.R2_BUCKET;
+      await uploadStatus({ busy: true, ts: Date.now() });
+      expect(mockSend).not.toHaveBeenCalled();
+    });
+
+    it('should not throw on upload failure', async () => {
+      mockSend.mockRejectedValueOnce(new Error('Network error'));
+      await expect(
+        uploadStatus({ busy: true, ts: Date.now() })
+      ).resolves.not.toThrow();
+    });
+  });
+});

package/__tests__/properties.test.ts

@@ -0,0 +1,94 @@
+/**
+ * R2 Status Hook - Property-Based Tests
+ *
+ * Validates correctness properties of the status payload.
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { StatusPayload } from '../handler';
+
+const minTimestamp = new Date('2020-01-01').getTime();
+const maxTimestamp = new Date('2030-01-01').getTime();
+const timestampArb = fc.integer({ min: minTimestamp, max: maxTimestamp });
+
+const sessionKeyArb = fc.string({ minLength: 1, maxLength: 50 });
+const sourceArb: fc.Arbitrary<string | undefined> = fc.oneof(
+  fc.constant(undefined as undefined),
+  fc.constantFrom('telegram', 'whatsapp', 'test')
+);
+
+const statusPayloadArb = fc.record({
+  busy: fc.boolean(),
+  ts: timestampArb,
+  sessionKey: fc.oneof(fc.constant(undefined as undefined), sessionKeyArb),
+  source: sourceArb,
+});
+
+function itProperty(name: string, property: fc.IProperty<any>, numRuns = 50) {
+  it(name, () => {
+    fc.assert(property, { numRuns });
+  });
+}
+
+describe('StatusPayload properties', () => {
+  describe('JSON serialization round-trip', () => {
+    itProperty('serialization and parsing produces equivalent object',
+      fc.property(statusPayloadArb, (payload) => {
+        const serialized = JSON.stringify(payload);
+        const parsed = JSON.parse(serialized);
+
+        return (
+          parsed.busy === payload.busy &&
+          parsed.ts === payload.ts &&
+          (payload.sessionKey !== undefined ? parsed.sessionKey === payload.sessionKey : parsed.sessionKey === undefined) &&
+          (payload.source !== undefined ? parsed.source === payload.source : parsed.source === undefined)
+        );
+      })
+    );
+
+    itProperty('round-trip preserves field types',
+      fc.property(statusPayloadArb, (payload) => {
+        const parsed = JSON.parse(JSON.stringify(payload));
+        return (
+          typeof parsed.busy === 'boolean' &&
+          typeof parsed.ts === 'number'
+        );
+      })
+    );
+  });
+
+  describe('JSON size limit', () => {
+    itProperty('serialized JSON is less than 1024 bytes',
+      fc.property(statusPayloadArb, (payload) => {
+        const json = JSON.stringify(payload);
+        return new Blob([json]).size < 1024;
+      })
+    );
+  });
+
+  describe('timestamp validity', () => {
+    itProperty('timestamps are valid Unix epoch milliseconds',
+      fc.property(timestampArb, (ts) => {
+        const date = new Date(ts);
+        return date.getTime() === ts && ts >= minTimestamp;
+      })
+    );
+  });
+
+  describe('busy state mapping', () => {
+    itProperty('command:new always maps to busy: true',
+      fc.property(timestampArb, sessionKeyArb, sourceArb, (ts, sessionKey, source) => {
+        const payload: StatusPayload = { busy: true, ts, sessionKey, source };
+        return payload.busy === true;
+      })
+    );
+
+    itProperty('command:stop always maps to busy: false',
+      fc.property(timestampArb, sessionKeyArb, sourceArb, (ts, sessionKey, source) => {
+        const payload: StatusPayload = { busy: false, ts, sessionKey, source };
+        return payload.busy === false;
+      })
+    );
+  });
+});

package/handler.ts

@@ -0,0 +1,120 @@
+/**
+ * R2 Status Hook - Handler
+ *
+ * Pushes agent busy/idle status to Cloudflare R2 on command events.
+ * Follows the OpenClaw HookHandler convention.
+ */
+
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { config } from 'dotenv';
+
+config();
+
+/**
+ * Status payload uploaded to R2
+ */
+export interface StatusPayload {
+  busy: boolean;
+  ts: number;
+  sessionKey?: string;
+  source?: string;
+}
+
+/**
+ * Lazily initialized S3 client (created on first use)
+ */
+let client: S3Client | null = null;
+
+function getClient(): S3Client {
+  if (!client) {
+    client = new S3Client({
+      region: 'auto',
+      endpoint: process.env.R2_ENDPOINT,
+      credentials: {
+        accessKeyId: process.env.R2_ACCESS_KEY_ID ?? '',
+        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY ?? '',
+      },
+    });
+  }
+  return client;
+}
+
+/**
+ * Uploads status payload to R2.
+ * Does not throw — catches errors and logs them.
+ */
+export async function uploadStatus(payload: StatusPayload): Promise<void> {
+  const bucket = process.env.R2_BUCKET;
+  if (!bucket) {
+    console.error('[r2-status] R2_BUCKET not set, skipping upload');
+    return;
+  }
+
+  try {
+    await getClient().send(
+      new PutObjectCommand({
+        Bucket: bucket,
+        Key: 'status.json',
+        Body: JSON.stringify(payload),
+        ContentType: 'application/json',
+        CacheControl: 'no-cache',
+      })
+    );
+    console.log(`[r2-status] Uploaded status (busy: ${payload.busy})`);
+  } catch (err) {
+    console.error(
+      '[r2-status] Upload failed:',
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * OpenClaw HookHandler
+ *
+ * Listens for command events:
+ * - command:new   → busy: true
+ * - command:stop  → busy: false
+ * - command:reset → busy: false
+ */
+const handler = async (event: {
+  type: string;
+  action: string;
+  sessionKey: string;
+  timestamp: Date;
+  messages: string[];
+  context: {
+    commandSource?: string;
+    senderId?: string;
+    [key: string]: unknown;
+  };
+}): Promise<void> => {
+  if (event.type !== 'command') {
+    return;
+  }
+
+  let busy: boolean;
+  switch (event.action) {
+    case 'new':
+      busy = true;
+      break;
+    case 'stop':
+    case 'reset':
+      busy = false;
+      break;
+    default:
+      return;
+  }
+
+  const payload: StatusPayload = {
+    busy,
+    ts: event.timestamp.getTime(),
+    sessionKey: event.sessionKey,
+    source: event.context.commandSource,
+  };
+
+  // Fire and forget — don't block command processing
+  void uploadStatus(payload);
+};
+
+export default handler;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "openclaw-face-hooks",
+  "version": "0.0.1",
+  "description": "OpenClaw hook for pushing agent status to Cloudflare R2",
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:push": "tsx test-push.ts"
+  },
+  "keywords": [
+    "openclaw",
+    "hooks",
+    "r2",
+    "face"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "fast-check": "^3.15.0",
+    "tsx": "^4.21.0",
+    "vitest": "^1.0.4"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.450.0",
+    "dotenv": "^17.2.4"
+  },
+  "openclaw": {
+    "hooks": [
+      "./"
+    ]
+  }
+}

package/test-push.ts

@@ -0,0 +1,61 @@
+/**
+ * R2 Status Hook - Integration Test
+ *
+ * Simulates command events to verify R2 push functionality.
+ * Requires R2 environment variables to be set (or .env file).
+ *
+ * Usage: pnpm test:push
+ */
+
+import { config } from 'dotenv';
+import { resolve } from 'path';
+
+config({ path: resolve(__dirname, '.env') });
+
+import { uploadStatus, StatusPayload } from './handler';
+
+const REQUIRED_VARS = ['R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY', 'R2_ENDPOINT', 'R2_BUCKET'] as const;
+
+const missing = REQUIRED_VARS.filter((v) => !process.env[v]);
+if (missing.length > 0) {
+  console.warn(`Warning: Missing environment variables: ${missing.join(', ')}`);
+  console.warn('Set them or create a .env file. Continuing anyway...\n');
+}
+
+async function testPush(label: string, payload: StatusPayload): Promise<boolean> {
+  console.log(`--- ${label} ---`);
+  try {
+    await uploadStatus(payload);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  console.log('=== R2 Status Push Integration Test ===\n');
+
+  const test1 = await testPush('Test 1: command:new (busy: true)', {
+    busy: true,
+    ts: Date.now(),
+    sessionKey: 'agent:main:main',
+    source: 'test',
+  });
+
+  await new Promise((r) => setTimeout(r, 2000));
+
+  const test2 = await testPush('Test 2: command:stop (busy: false)', {
+    busy: false,
+    ts: Date.now(),
+    sessionKey: 'agent:main:main',
+    source: 'test',
+  });
+
+  console.log('\n=== Results ===');
+  console.log('command:new  push:', test1 ? 'PASSED' : 'FAILED');
+  console.log('command:stop push:', test2 ? 'PASSED' : 'FAILED');
+
+  process.exit(test1 && test2 ? 0 : 1);
+}
+
+main();

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["*.ts", "__tests__/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}