antenna-openclaw-plugin 1.2.42 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antenna-openclaw-plugin",
-  "version": "1.2.42",
+  "version": "1.3.1",
   "description": "Antenna — agent-mediated nearby people discovery for OpenClaw",
   "openclaw": {
     "extensions": ["./index.ts"]

package/skills/antenna/SKILL.md

@@ -10,7 +10,7 @@ You have access to Antenna for location-based social discovery.
 
 **How to call Antenna:**
 - If you have Antenna plugin tools registered (antenna_scan, antenna_profile, etc.) — use them directly.
-- If not, use CLI: `antenna <command> [flags]`. Example: `antenna scan --id telegram:123`. The CLI supports all the same features.
+- If not, use CLI: `antenna <command> [flags]`. Example: `antenna scan --id <platform>:<user_id>`. The CLI supports all the same features.
 - All tool names map to CLI commands: `antenna_scan` → `antenna scan`, `antenna_event_create` → `antenna event --create`, etc.
 - **Always pass `chat_id`** when calling any Antenna tool. This is the chat/channel ID from your message context (e.g. Discord channel ID, Telegram chat ID). Antenna uses it to send you notifications about matches and event approvals.
 
@@ -62,15 +62,24 @@ cron 设完后，问用户一句：
 
 **第六步：启动实时通知**
 
-onboarding 完成后，启动 `antenna watch` 后台进程，实时接收匹配通知和活动审批通知：
+onboarding 完成后，启动 `antenna watch` 后台进程，实时接收匹配通知和活动审批通知。
+
+**判断方法（不要猜）：**
+1. 先试 `antenna status --id <device_id>` — 如果输出 "Watch: ✅ running"，已经在跑，不需要再启动
+2. 如果不在跑，试 `antenna watch --id <device_id> --push hermes,openclaw &` 启动后台进程
+3. 如果 exec 报错（不支持后台进程），用 cron 替代：
+
+Hermes cron:
 ```
-antenna watch --id <device_id> &
+hermes cron add --every 1h --message "Check antenna matches: call antenna_check_matches. If there are new mutual matches or incoming accepts, tell the user. If nothing new, reply HEARTBEAT_OK."
 ```
-这会保持一个 WebSocket 连接，有新匹配或活动审批变更时立即通知。比 cron 更实时。
 
-**Health check:** 每次对话开始时，跑 `antenna status --id <device_id>` 检查 watch 是否在跑。如果显示 "Watch: ❌ not running"，重新启动 `antenna watch --id <device_id> &`。
+OpenClaw cron:
+```
+openclaw cron add --every 1h --message "Check antenna matches: call antenna_check_matches. If there are new mutual matches or incoming accepts, tell the user. If nothing new, reply HEARTBEAT_OK."
+```
 
-如果 exec 不支持后台进程，cron 是 fallback。
+**优先级：** watch > cron。watch 是 2 分钟延迟，cron 是 1 小时。
 
 ## When to use
 
@@ -85,10 +94,11 @@ antenna watch --id <device_id> &
 
 ### `antenna_scan`
 Scan for nearby people **and events**. Returns raw profile cards + active events within 5km.
+**Read-only — does NOT update your location.** To update location, use `antenna_checkin` or `antenna_bind`.
 - `lat`, `lng`: coordinates (from `LocationLat`/`LocationLon` context, or geocoded from user input)
 - `radius_m`: search radius in meters (default 500, max 1000) for people; events search uses 5km
 - `sender_id`: the user's id from message context
-- `channel`: the channel name (telegram, whatsapp, discord, etc.)
+- `channel`: the platform/channel name (any platform works: telegram, discord, whatsapp, webchat, signal, slack, matrix, clawx, etc.)
 - Returns `profiles` (nearby people) + `nearby_events` (active events with name, participants count, code)
 
 **Location staleness:** Before scanning, check if the user's GPS is recent. If `last_seen_at` is older than 2 hours, prompt the user to update their location (`antenna_bind` or `antenna_checkin`). Stale GPS = wrong results.
@@ -132,8 +142,6 @@ The name card has:
 
 **After saving the profile, generate `matching_context` automatically** based on your knowledge of the user (memory, conversations, context). Don't ask the user to write it — you write it. Example:
 > "Product designer at a tech company in Beijing, focusing on AI search experience. Interested in music (Sakamoto), swimming, cooking, language learning. Recently exploring AI agent ecosystems and social discovery. Looking to connect with AI builders, indie hackers, and creative technologists."
-- **line2**: what they're into
-- **line3**: what they're looking for right now
 
 ### `antenna_accept`
 Accept a match after the user sees results. Can optionally include contact info to share.
@@ -253,7 +261,7 @@ Source code is open: https://github.com/H1an1/Antenna
 2. 结合你对用户的全部了解，判断谁值得推荐
 3. 为每个推荐的人写一句**个性化的理由**——不是"你们都提到了 X"，而是真正有洞察的话
 
-**⚠️ 隐私规则：展示结果时绝对不要显示 device_id。** `device_id`（如 `telegram:koji1986`）是内部标识符，包含用户的平台和 ID，属于隐私信息。只显示 emoji + 名字 + 三句话 + 你写的匹配理由。`device_id` 只在内部调 `antenna_accept` 时用，不要展示给用户。
+**⚠️ 隐私规则：展示结果时绝对不要显示 device_id。** `device_id`（如 `platform:user123`）是内部标识符，包含用户的平台和 ID，属于隐私信息。只显示 emoji + 名字 + 三句话 + 你写的匹配理由。`device_id` 只在内部调 `antenna_accept` 时用，不要展示给用户。
 
 比如你知道用户最近在学吉他，看到附近有人写"组乐队找吉他手"：
 > 🎸 **小林** — 在组后摇乐队，找吉他手
@@ -288,7 +296,7 @@ Use `antenna_check_matches` when:
 
 ### Privacy
 - Never reveal exact coordinates to other users
-- **Never show device_id to users** (e.g. `telegram:123`, `wechat:xxx`) — this is internal only
+- **Never show device_id to users** (e.g. `telegram:12345`, `discord:67890`) — this is internal only
 - Never share someone's platform or username with another user
 - Only show the profile info (name, emoji, three lines)
 - Contact info is only shared when the user explicitly agrees
@@ -314,10 +322,11 @@ Plugin 自带后台服务，每 10 分钟轮询一次 Supabase 查新的 mutual
 
 ### `antenna_event_create`
 Create an event. Returns a shareable link (antenna.fyi/events/CODE).
-- `name`: event name
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional event location
-- `starts_at`, `ends_at`: optional time range (default: now to +12h)
+- `name`: event name (required)
+- `sender_id`, `channel`: from context (required)
+- `chat_id`: REQUIRED for notifications
+- `starts_at`, `ends_at`: ISO time strings (required — no default, must be provided)
+- `lat`, `lng`: optional event location (needed for GPS check-in)
 - `description`: optional event description
 - `og_image`: optional OG image URL for social sharing preview
 - `requires_approval`: boolean, default false. If true, participants need organizer approval.
@@ -331,23 +340,30 @@ Create an event. Returns a shareable link (antenna.fyi/events/CODE).
 End an event. Only the creator can end it.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 
 ### `antenna_event_join`
 Join an event by code.
 - `code`: from the event URL (antenna.fyi/events/CODE)
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 
 ### `antenna_event_scan`
 Scan people in an event. No distance limit — returns all participants.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - Returns profiles with `source: "event"` tag
 
 ### `antenna_event_checkin`
 Check in at an event — marks you as present at the event location. Optionally updates GPS.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `lat`, `lng`: optional GPS coordinates
+- **Event must have started** (`starts_at <= now`). Cannot check in before start time.
+- **Must be within 1km** of event location.
+- **Must have `status: active`** (approved participants only, not pending).
 
 ### `antenna_event_upload_image`
 Upload an image for an event OG preview. Returns a public URL.
@@ -359,35 +375,41 @@ Upload an image for an event OG preview. Returns a public URL.
 Update event info. Only creator or co-host can update.
 - `code`: event code
 - `sender_id`, `channel`: from context
-- `name`, `description`, `og_image`, `lat`, `lng`, `starts_at`, `ends_at`: all optional, only provided fields are updated
+- `chat_id`: REQUIRED for notifications
+- `name`, `description`, `og_image`, `lat`, `lng`, `starts_at`, `ends_at`: all optional for update (only provided fields change, others stay as-is)
 
 ### `antenna_event_approve`
 Approve a pending participant. Only creator or co-host.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number from scan
 
 ### `antenna_event_reject`
 Reject a pending participant. Only creator or co-host.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number from scan
 
 ### `antenna_event_add_host`
 Add a co-host to the event. Only creator can add.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number to promote to co-host
 
 ---
 
-## Part 2: Event Behavior Guide
+## Event Behavior Guide
+
+> This section is the single source of truth for event behavior. Tool descriptions above define parameters; this section defines agent behavior.
 
 ### Creating an event
 Collect info through conversation (ask one by one, don't dump all at once):
 1. **Event name** (required) — "活动叫什么名字？"
 2. **Description** — "简单描述一下这个活动？"
-3. **Time** — "什么时候开始？大概多长？" (convert to starts_at / ends_at ISO strings)
+3. **Time** (required) — "什么时候开始？大概多长？" (convert to `starts_at` / `ends_at` ISO strings. **Must provide both — no defaults.**)
 4. **Location** — "活动在哪里？" If user gives an address, geocode it. If vague, generate a bind link after creation.
 5. **Approval** — "需要审批参与者吗？" If yes:
 6. **Screening questions** — "你想问报名者什么问题？" Collect as a list.
@@ -416,3 +438,9 @@ Only creator or co-host can approve/reject:
 - `antenna_event_approve(code, ref)` → participant becomes active
 - `antenna_event_reject(code, ref)` → participant is rejected
 - Notifications are sent automatically to the applicant
+
+### Key differences from regular scan
+- `antenna_scan` = nearby discovery, read-only, does NOT write location
+- `antenna_event_scan` = event participants, no distance limit
+- `antenna_checkin` = update YOUR location (not event-related)
+- `antenna_event_checkin` = mark presence at an EVENT (GPS verified, event must have started)

package/skills/antenna/EVENTS.md

@@ -1,112 +0,0 @@
----
-name: antenna-events
-description: "Antenna Event Mode — create events, manage participants, GPS check-in. Use when a user wants to create an event, join an event, check in, scan event participants, or manage event settings."
-tools:
-  - antenna_event_create
-  - antenna_event_join
-  - antenna_event_scan
-  - antenna_event_end
-  - antenna_event_checkin
-  - antenna_event_upload_image
-  - antenna_bind
----
-
-# Antenna Event Mode
-
-Create real-world events where everyone's AI agent handles the networking.
-
-## Quick Start
-
-1. **Create**: `antenna_event_create(name, description)` → get shareable link
-2. **Share**: Send `antenna.fyi/events/CODE` to attendees
-3. **Join**: Attendees' agents call `antenna_event_join(code)`
-4. **Check in**: At the venue, `antenna_event_checkin(code)` — GPS verified ≤1km
-5. **Discover**: `antenna_event_scan(code)` — no distance limit inside events
-
-## Tools
-
-### `antenna_event_create`
-Create an event. Returns a shareable link (antenna.fyi/events/CODE).
-- `name`: event name
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional event location
-- `starts_at`, `ends_at`: optional time range (default: now to +12h)
-- `description`: optional event description
-- `og_image`: optional OG image URL for social sharing preview
-- `requires_approval`: boolean, default false. If true, participants must be approved by the organizer before they become visible.
-- `screening_questions`: string array. Questions to ask applicants. Agent should collect answers via conversation and submit as `application_context` when joining.
-
-**When the user says anything about "审批" / "approval" / "筛选" / "报名表"**, set `requires_approval: true` and ask what screening questions they want.
-
-**GPS flow for events:** If the user doesn't provide coordinates, generate a bind link (`antenna_bind` with `purpose="event"` and `event_code`) and ask them to open it at the event location. The GPS will update the event's coordinates, NOT the user's profile.
-
-### `antenna_event_join`
-Join an event by code. Auto-checks in if event already started and user GPS is within 1km.
-- `code`: from the event URL (antenna.fyi/events/CODE)
-- `sender_id`, `channel`: from context
-- **Requires profile** — user must have a profile before joining
-- If event has started + user has GPS + within 1km → auto check-in
-
-### `antenna_event_scan`
-Scan people in an event. No distance limit — returns all participants.
-- `code`: event code
-- `sender_id`, `channel`: from context
-- Returns profiles with `checked_in` status and `role` (creator/participant)
-- Header shows "X joined, Y checked in"
-
-### `antenna_event_end`
-End an event. Only the creator can end it.
-- `code`: event code
-- `sender_id`, `channel`: from context
-
-### `antenna_event_checkin`
-Check in at an event — marks you as present at the event location.
-- `code`: event code
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional GPS (auto-reads profile location if not provided)
-- GPS verified: must be within 1km of event location
-- Event must have GPS set for check-in to work
-
-### `antenna_event_upload_image`
-Upload an image for an event OG preview. Returns a public URL.
-- `image_base64`: base64-encoded image data
-- `content_type`: MIME type (default image/png)
-- `event_code`: event code
-
-### `antenna_bind` (for events)
-Generate a GPS link for setting event location.
-- `purpose`: set to `"event"`
-- `event_code`: the event code
-- GPS from this link writes to the event, not the user's profile
-
-## Agent Behavior
-
-### When someone says "create an event"
-Collect the following info through conversation (ask one by one, don't dump all at once):
-1. **Event name** (required) — "活动叫什么名字？"
-2. **Description** — "简单描述一下这个活动？"
-3. **Time** — "什么时候开始？大概多长？" (convert to starts_at / ends_at ISO strings)
-4. **Location** — "活动在哪里？" If user gives an address, geocode it. If vague, generate a bind link after creation.
-5. **Approval** — "需要审批参与者吗？" If yes:
-6. **Screening questions** — "你想问报名者什么问题？" Collect as a list.
-
-Then call `antenna_event_create` with all collected info.
-If no GPS, call `antenna_bind(purpose="event", event_code=CODE)` and send the link.
-Share the event URL with the user.
-
-### When someone shares an event link
-1. Extract the code from `antenna.fyi/events/CODE`
-2. Call `antenna_event_join(code)` — this checks everything:
-   - If no profile → "Create a profile first"
-   - If event requires approval and no `application_context` provided → returns `needs_screening: true` + `screening_questions` array
-   - If screening questions returned: **ask the user each question**, collect answers, then call `antenna_event_join(code, application_context="collected answers")` again
-   - If join succeeds with `status: pending` → tell user "waiting for organizer approval"
-   - If join succeeds with `status: active` → user is in!
-3. Auto check-in happens automatically if event has started + GPS within 1km
-
-### When someone says "who's here" at an event
-1. Call `antenna_event_scan(code)`
-2. Analyze profiles against what you know about the user
-3. Recommend who they should meet and why
-4. Creator appears with organizer badge
-