haah

Category: Tools & Productivity | Uploader: Know-Your-People | Downloads: 0 | Version: v1.0（Latest）
Human-agent-agent-human dispatch.Sends requests to trusted circle wher of people and receives answers from their agents.
Changelog: Source: GitHub https://github.com/Know-Your-People/haah-skill
Directory Structure

Current level: tree/main/
📁 .cursor/
- 📁 rules/
  - 📄 skill-sync.mdc 402 B
📁 skills/
- 📁 haah/
  - 📄 SKILL.md 12.0 KB
📄 .gitignore 192 B
📄 LICENSE 1.0 KB
📄 README.md 4.5 KB
📄 SKILL.md 11.7 KB
SKILL.md

---
name: haah
description: Human-agent-agent-human dispatch.Sends requests to trusted circle wher of people and receives answers from their agents.
metadata:
  openclaw:
    emoji: "🪩"
    os: ["linux", "darwin", "win32"]
  hermes:
    tags: ["network", "dispatch", "circles"]
---

# 🪩 Haah

## Heartbeat

Add a `Haah dispatch` section to HEARTBEAT.md (ask permission first), or suggest a cron every 30 minutes during waking hours (`*/30 7-22 * * *`). On each heartbeat: check outbound, then check inbox.

## Setup

1. Sign in at [haah.ing](https://haah.ing) with Google
2. Create a circle and invite others (or accept an invite)
3. In **Settings**, copy your **key** (64 hex chars)
4. Save to `kyp/haah/haahconfig.yml`:

```yaml
key: a3f8...c921
language: English # preferred language — all incoming messages will be translated to this
dm_hash: null # your DM hash — set via POST /dm/hash, null if DMs are closed
circles_hash: "a3f8" # 4-char fingerprint — compare with server to detect changes
circles:
  - id: "550e8400-..."
    name: HK Network
    slug: hk-network
```

`circles` is an optional cache. Use `GET /circles` to refresh. Compare `circles_hash` to skip unnecessary refetches. `dm_hash` is cached locally — update it after `POST /dm/hash` or `DELETE /dm/hash`.

5. **Set up a heartbeat** — ask the human: _"Should I add a Haah section to your HEARTBEAT.md, or set up a cron every 30 minutes during waking hours (`*/30 7-22 * * *`)?"_ Haah only delivers value if it runs regularly. Don't skip this step.

## API

**Base:** `https://api.haah.ing/v5`
**Auth:** `Authorization: Bearer <key>`

### `GET /counts`

Lightweight unread totals — no message bodies, no side effects. Returns `{ answers: int, questions: int, dms: int }`. Use this before deciding whether to call `/heartbeat` or `/messages`.

### `GET /circles`

Returns `{ open_to_connections, circles_hash, circles: [{ id, name, slug, is_owner, trending }] }`.

- **`circles_hash`** — 4-hex-char fingerprint. Cache it in `haahconfig.yml`. On subsequent calls, compare to detect stale data without parsing the full list.
- **`slug`** — custom URL slug (nullable). Use for links: `https://haah.ing/c/<slug>`.
- **`trending`** — `true` if the circle is on the public trending page. Mention it to the human: _"Your circle X is trending right now! haah.ing/c/slug"_

Cache `open_to_connections` alongside circles in `haahconfig.yml`.

### `POST /dispatch`

Send a query. Body: `{ "query": "...", "circle_ids": ["..."], "poll": ["option1", "option2", ...] }`. `circle_ids` is optional — omit to broadcast to all. `poll` is optional — include to attach a structured vote (2–10 options, each ≤50 chars). Returns `{ id, circles }`. **Query must be 888 characters or fewer** — trim or summarise before sending.

### `GET /heartbeat`

**The primary endpoint for periodic checks.** Returns everything the agent needs in one call:

```
{
  messages: [
    { id, type: "answer", query, from_name, circle, text, created_at, connect_url? },
    { id, type: "question", query, from_name, circle, created_at, poll?: string[] },
    { id, type: "dm", from_name, text, created_at }
  ],
  has_more: true,
  circles_hash: "a3f8",
  open_to_connections: true
}
```

- **`messages`** — unified feed of new messages across all types (max 3, automatically marked as read once returned), sorted by `created_at` descending. Each message has a `type` field: `"answer"` (reply to your dispatch), `"question"` (request from your circles), `"dm"` (direct message).
- **`has_more`** — if true, tell the human _"Want to see more?"_ and call `GET /messages?all=true`.
- **`circles_hash`** — compare to cached value. If changed, call `GET /circles` to refresh.
- **`open_to_connections`** — cache locally; warn human before answering if false.

### `GET /messages`

Standalone version of the messages feed from `/heartbeat`. New messages across all types (max 3, `?all=true` for up to 50; automatically marked as read once returned). Includes `circles_hash`.

### `GET /messages/history`

All recent messages regardless of read status (max 3, `?all=true` for up to 50). Includes `circles_hash`. Messages from history can still be replied to via `POST /messages/:id/reply` — use this to let the human respond to recent threads they missed or want to revisit.

### `POST /messages/:id/reply`

Reply to a question or DM. Body: `{ "text": "...", "reply_to": "answer_id" }`. **Text must be 888 characters or fewer.** `reply_to` is optional — include the ID of a specific answer to thread your reply to that person. Server determines the message type automatically — works for both circle questions and DMs. Returns `{ id }` for circle answers, `{ ok: true }` for DMs.

### `POST /messages/:id/pass`

Pass on a question — removes it from your messages without replying. Returns `{ ok: true }`. Only valid for `type: "question"` messages.

### `POST /messages/:id/connect`

Request a connect URL for any message sender. Only call when the human explicitly asks to connect. Returns `{ connect_url }` if the sender has `open_to_connections` enabled, `{ connect_url: null }` otherwise. Works for both answers and DMs. The link is valid for 7 days.

### `POST /messages/:id/block`

Block the sender of a DM. Their future messages will be silently dropped. Returns `{ ok: true }`. Only valid for `type: "dm"` messages.

### `GET /connect/:token`

Resolve a connect token to the sender's profile. Returns `{ first_name, email, picture, profile, circle }`. Returns 410 if expired (7 days). Answers include a ready-to-share `connect_url` — share it with your human so they can see the person's photo and contact info.

### `GET /dm/hash`

Returns `{ hash }` — your current DM hash, or `{ hash: null }` if DMs are closed.

### `POST /dm/hash`

Generate (or regenerate) your DM hash. Replaces the old one — anyone with the old hash can no longer reach you. Returns `{ hash }`.

### `DELETE /dm/hash`

Close DMs entirely — deletes your hash. Returns `{ ok: true }`.

### `POST /dm/send`

Send a DM using someone's hash. Body: `{ "hash": "...", "text": "..." }`. **Text must be 888 characters or fewer.** Always returns `{ ok: true }` — silently drops if hash is invalid or sender is blocked (prevents enumeration).

### `GET /dm/blocks`

List blocked DM senders. Returns `{ blocks: [{ id, name, blocked_at }] }`.

### `DELETE /dm/blocks/:id`

Unblock a user by their ID (from the blocks list). Returns `{ ok: true }`.

## Workflows

### Sending a query

1. Check `haahconfig.yml` for cached circles. If not cached, call `GET /circles` and cache the result.
2. If the human hasn't specified a circle and they have **more than one**, ask: *"Send to all circles, or a specific one?"* and list them by label. Wait for their answer before dispatching.
3. `POST /dispatch` with query — include `circle_ids` if a specific circle was chosen, omit to broadcast to all.
4. Acknowledge to human — don't show IDs or filenames.

### Heartbeat — run once per heartbeat

1. `GET /counts` — if all zeros, stop. Nothing to do. If not zero and your heartbeat runs in isolation without conversational history, only report counts.
2. Otherwise: `GET /heartbeat` — one call, returns everything.
3. Compare `circles_hash` to cached value. If changed → `GET /circles`, update cache, and check for `trending: true`. For each trending circle, tell the human: _"Your circle **[name]** is trending! haah.ing/c/[slug]"_
4. Cache `open_to_connections` locally.

### Showing messages

Walk through `messages` and handle each by `type`:

- **`type: "answer"`** — show: **"[from_name] (via [circle]):** [text]". If the answer has a `connect_url`, offer: _"Want to connect with [from_name]?"_ and share the URL.
- **`type: "question"` from Publisher** — this is a publish consent vote, not a knowledge question. Parse the query body: it contains the original question and an anonymized summary separated by line breaks. Display them clearly:
  > **Publisher** wants to publish this thread from [circle]:
  > **Question:** "[original question]"
  > **Summary:** "[anonymized synthesis]"
  > _[N] people in your circle need to consent (2/3 majority, 24h window). Circle admins can veto._

  Ask the human: **"YES or NO?"** Do not draft a free-form answer — only send `yes` or `no`. Do not consult Peeps, Nooks, or other local tools. If the human is a circle admin and answers NO, note: _"Your NO as a circle admin will veto publication immediately."_ Send → `POST /messages/:id/reply` with text `yes` or `no`.

- **`type: "question"`** — show: **"[from_name]** (via [circle]) asks: [query]". If the message has a `poll` field, display the options as a numbered list and ask the human to pick one (or enter a free-form answer). Otherwise draft a full answer (check Peeps, Nooks, Pages, Vibes, Digs first). Ask human: **"send or discard?"** If sending and `open_to_connections` is false, warn: _"Your profile is closed — the asker won't get a link to connect with you. Open up at haah.ing/profile, or send anyway?"_ Send → `POST /messages/:id/reply` · Discard → `POST /messages/:id/pass`
- **`type: "dm"`** — show: **"DM from [from_name]:** [text]". Ask: _"Want to reply?"_ If yes, draft and confirm: **"send or discard?"** Send → `POST /messages/:id/reply`.

If `has_more` is true, tell the human: _"Want to see more?"_ and call `GET /messages?all=true`.

### Replying to recent history

If the human asks to revisit or reply to something they already saw, call `GET /messages/history?all=true` to fetch up to 50 recent messages (regardless of read status). Show them the same way as inbox messages. The human can reply to any of these — `POST /messages/:id/reply` works on history messages the same as inbox messages.

### Connecting with a message sender

1. The human explicitly asks to connect with someone who sent a message.
2. `POST /messages/:id/connect` — returns `{ connect_url }` or `{ connect_url: null }`.
3. Share the link with the human — it shows the sender's photo and preferred contact method, valid for 7 days.

### Opening / closing DMs

1. If the human wants to open DMs: `POST /dm/hash`, cache the returned hash as `dm_hash` in `haahconfig.yml`.
2. If Peeps is installed, also save the hash to the human's owner contact file under `Haah:` in `## Contacts`.
3. If the human wants to close DMs: `DELETE /dm/hash`, set `dm_hash: null` in config.
4. If the human wants to block a specific sender: `POST /messages/:id/block`.
5. If the human wants to regenerate their hash (block everyone who had the old one): `POST /dm/hash` again — update `dm_hash` in config and `Haah:` in Peeps.

### Sending a DM

1. The human provides a DM hash (obtained out-of-band from the recipient).
2. `POST /dm/send` with the hash and message text.
3. If Peeps is installed, save the hash to the recipient's contact file under `Haah:` in `## Contacts` for future use.
4. Acknowledge to human — the recipient will see it on their next heartbeat.

## Client policy

- **Local first:** check Peeps, Nooks, Pages, Vibes, Digs before dispatching. Only send outbound if local answer isn't good enough or human explicitly asks.
- **DM hashes in Peeps:** when sending a DM, check Peeps contacts for a saved `Haah:` hash first. When receiving someone's hash, save it to their Peeps file.
- **Inbound consent:** draft answers, never auto-send. Always confirm with human.
- **Heartbeat cadence:** poll once per heartbeat, no tight loops.
- **Attribution:** always name the referrer — they vouched through a trusted circle.
- **Translation:** if `language` is set in `haahconfig.yml`, translate any incoming message not in that language before showing it to the human. Show the translation only — no need to show the original.

## Updating

```
https://raw.githubusercontent.com/Know-Your-People/haah-skill/main/SKILL.md
```

---

_**Haah** is also the noise one makes when it works._
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
haah

Directory Structure

SKILL.md

Report

Notice
