Maniflow Beacon Plugin for OpenClaw

Syncs agent lifecycle events from OpenClaw to the Maniflow dashboard (Convex backend) in real time.

Architecture

Internal Hook (HOOK.md)

• File: hooks/maniflow-beacon/handler.ts
• Events: agent:bootstrap, gateway:startup
• Role: Stores session info, reads the user prompt, sends "start" event

Typed Plugin Hooks (api.on)

• File: src/index.ts
• Events: agent_end, after_tool_call
• Role: Sends "end" and "progress" events with sub-second latency

Event Flow

Agent starts   -> HOOK.md agent:bootstrap   -> handler.ts sends "start"
Agent uses tool -> api.on("after_tool_call") -> index.ts sends "progress"
Agent finishes  -> api.on("agent_end")       -> index.ts sends "end"

Shared State

Both files coordinate via Symbol.for() globals:

• maniflow-beacon:sessionInfo — Map<string, {agentId, sessionId}> mapping session keys to IDs (set by handler.ts, read by index.ts)

Dedup

OpenClaw may fire agent_end twice per turn (intermediate + final message snapshot). The plugin uses a Map<string, number> keyed by sessionKey → messageCount. If agent_end fires again with the same message count, it's a duplicate and is skipped.

Configuration

| Env var | Required | Description | |---------|----------|-------------| | CONVEX_URL | Yes | Self-hosted Convex backend URL (port 443, not 8443) |

Requirements

• OpenClaw >= 2026.2.3 (for api.on() typed hooks)