open-index/open-npm huggingface dataset:
npm package: @maniflow/beacon
Description: Maniflow Beacon plugin for OpenClaw - enables task queue and event reporting
Latest version: 0.1.18

# 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)