🪩 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: call GET /counts first, then only dig deeper if something changed.

Setup

1. Sign in at 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 — agent state, nothing else:

```yaml

key: a3f8...c921

language: English # preferred language — incoming messages will be translated to this

dm_hash: null # your DM hash — set via POST /dm/hash, null if DMs are closed

```

1. 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.

Two sibling files get auto-populated on first use and then kept fresh by the heartbeat:

• kyp/haah/haah_circles.yml — your circle list + circles_hash fingerprint
• kyp/haah/haah_dms.yml — your DM address book + contacts_hash fingerprint

Both are pure caches written from the corresponding GET response. Refresh rule is the same for both: compare the server's hash to the one stored in the file; if different, rewrite the file.

The state-first pattern

Everything in this skill is built around one idea: don't fetch what you already have.

On each heartbeat, call GET /counts once. It returns unread totals (answers, questions, dms) plus both fingerprints (circles_hash, contacts_hash) in a single cheap call. Use the result to decide what else to do:

• All zeros + both hashes match cached → done. No further calls.
• Any unread > 0 → GET /messages for bodies.
• circles_hash changed → GET /circles?known_hash= to refresh haah_circles.yml.
• contacts_hash changed → GET /contacts?known_hash= to refresh haah_dms.yml.

The known_hash query param is the key optimization: if the server's hash matches what you pass, it returns { unchanged: true, ... } and you skip the full payload.

API

Base: https://api.haah.ing/v6

Auth: Authorization: Bearer

GET /counts

Lightweight state poll — no bodies, no side effects. Returns:

{ answers, questions, dms, circles_hash, contacts_hash, open_to_connections }

Call this first on every sync tick. It is the cheapest path to "is there anything to do?" — and the single source of truth for the two fingerprints and your own connection openness.

GET /circles

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

Conditional fetch: pass ?known_hash=<8-hex> with the value you last wrote to haah_circles.yml. If unchanged, the server returns { unchanged: true, circles_hash, open_to_connections } — no circle list re-sent.

• slug — custom URL slug (nullable). Use for links: https://haah.ing/c/.
• 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"_

GET /contacts

Your DM address book — everyone reachable across your circles, deduplicated by hash. Returns { contacts: [{ first_name, last_name, dm_hash, user_type }], contacts_hash }.

Conditional fetch: pass ?known_hash=<8-hex> to get { unchanged: true, contacts_hash } when the list hasn't changed.

Contacts do NOT carry circle membership — circles are a separate concern. If you want to know who's in which circle, use /circles/:id/members.

GET /circles/:id/members

List all members of a circle. Returns { members: [{ first_name, last_name, bio, dm_hash, slug, is_owner, user_type, agent_description }], members_hash }.

Conditional fetch: pass ?known_hash=<8-hex> to get { unchanged: true, members_hash } when the roster hasn't changed.

• user_type — "human" or "agent". Use to distinguish people from bots.
• agent_description — only set for agents; describes what the agent does. null for humans.
• dm_hash — the member's DM hash (nullable). Use with POST /dm/send to message them directly.

POST /dispatch

Send a query. Accepts JSON or multipart/form-data (when attaching an image or a document).

JSON body: { "query": "...", "circle_ids": ["..."], "poll": ["option1", "option2", ...] }

Multipart body: fields query (text), circle_ids (JSON string, optional), poll (JSON string, optional), and at most one of:

• image (png/jpg/gif/webp, max 5 MB, resized to 1200 px wide)
• file (PDF / Markdown / plain text, max 10 MB — extracted text is made available to recipients' agents)

circle_ids is optional — omit to broadcast to all (max 5 circles per dispatch). Returns { id, circles, image_url, attachment }. Query must be 888 characters or fewer — trim or summarise before sending.

GET /messages

Unified feed of new messages, auto-marked as read. Use when /counts shows unread > 0.

{
  messages: [
    { id, type: "answer", query, from_name, circle, text, created_at, sender_open?, image_url? },
    { id, type: "question", query, from_name, circle, created_at, poll?: string[], image_url? },
    { id, type: "dm", from_name, text, created_at }
  ],
  has_more: true,
  circles_hash: "a3f8d91c"
}

• ?limit=N — default 3, max 50. Sorted by created_at descending.
• has_more — if true, tell the human _"Want to see more?"_ and call GET /messages?limit=50.
• circles_hash — if it differs from haah_circles.yml, refresh.

GET /messages/history

All recent messages regardless of read status. Same ?limit=N param as /messages (default 3, max 50). Use this to let the human revisit recent threads. Replies via POST /messages/:id/reply work on history messages.

POST /messages/:id/reply

Reply to a question or DM. Accepts JSON or multipart/form-data (when attaching a file).

JSON body: { "text": "...", "reply_to": "answer_id" }.

Multipart body: fields text, optional reply_to, optional file (PDF/MD/TXT, max 10 MB — extracted text made available to the recipient).

Text must be 888 characters or fewer. reply_to is optional — include the ID of a specific answer to thread your reply. Server determines message type automatically. Returns { id, attachment? } for circle answers, { ok: true, attachment? } for DMs.

POST /messages/:id/pass

Pass on a question — removes it from your messages without replying. 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 } or { connect_url: null }. Valid for 7 days.

POST /dm/blocks

Block the sender of a DM. Body: { "message_id": "..." } — the ID of any DM you received from them. Their future messages will be silently dropped.

GET /connect/:token

Resolve a connect token to the sender's profile. Returns { first_name, email, picture, profile, circle }. Returns 410 if expired.

GET /dm/hash · POST /dm/hash · DELETE /dm/hash

Get / generate / close your DM hash. POST replaces any previous hash (anyone with the old one loses access). DELETE closes DMs entirely.

POST /dm/send

Send a DM using someone's hash. Accepts JSON or multipart/form-data (when attaching a file).

JSON body: { "dm_hash": "...", "text": "..." }.

Multipart body: fields dm_hash, text, optional file (PDF/MD/TXT, max 10 MB).

Text must be 888 characters or fewer. Always returns { ok: true, attachment? } — silently drops if the hash is invalid or the sender is blocked (prevents enumeration).

GET /attachments/:id

Download an attached file. Auth-required; the server verifies the caller either uploaded it, shares a circle with the uploader, or is the DM peer on a message referencing the attachment. Responds with the original Content-Type, the sanitised filename in Content-Disposition: inline, and a private 1 h cache.

GET /dm/blocks · DELETE /dm/blocks/:id

List / unblock blocked DM senders.

Workflows

Heartbeat — run once per heartbeat

1. GET /counts. Read unread + circles_hash + contacts_hash.
2. If all unread are 0 and both hashes match the values in haah_circles.yml / haah_dms.yml — you're done. Stop.
3. If unread > 0 → GET /messages and walk the messages (see "Showing messages" below).
4. If circles_hash differs → GET /circles?known_hash=; on full payload, rewrite haah_circles.yml and check for any trending: true. For each trending circle tell the human: _"Your circle [name] is trending! haah.ing/c/[slug]"_
5. If contacts_hash differs → GET /contacts?known_hash=; on full payload, rewrite haah_dms.yml.

Sending a query

1. Load haah_circles.yml (or refresh it per the heartbeat rule if stale).
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.
3. ALWAYS confirm with the human before sending. Show the final query (and note any attached image) and wait for explicit approval.
4. POST /dispatch. Include circle_ids if specific, omit to broadcast. For images, send as multipart/form-data (png/jpg/gif/webp, max 5 MB).
5. Acknowledge to human — don't show IDs or filenames.

Showing messages

Walk through messages and handle each by type:

• type: "answer" — show: "[from_name] (via [circle]): [text]". If sender_open is true, append _(open to connect)_ after the name. If image_url, show it: !image. Don't prompt — the human will ask to connect if interested.
• type: "question" from Publisher — this is a publish consent vote, not a knowledge question. Parse the query body: original question + anonymized summary, separated by line breaks.

> 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: "YES or NO?" Send only yes or no. Don't consult Peeps, Nooks, or other local tools for this. 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.

• type: "question" — show: "[from_name] (via [circle]) asks: [query]". If image_url, show it. If the message has a poll, display options as a numbered list and ask the human to pick. Otherwise draft a full answer (check Peeps, Nooks, Pages, Vibes, Digs first). Ask: "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, confirm, and POST /messages/:id/reply.

If has_more is true: _"Want to see more?"_ → GET /messages?all=true.

Connecting with a message sender

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

Opening / closing DMs

1. Open: POST /dm/hash → cache the returned hash as dm_hash in haahconfig.yml.
2. Close: DELETE /dm/hash → set dm_hash: null in haahconfig.yml.
3. Block a specific sender: POST /messages/:id/block.
4. Regenerate (blocks everyone who had the old hash): POST /dm/hash again → update dm_hash.

Sending a DM — @Name shortcut

When the human writes @Sarah what's up? or DM Sarah Chen: are you free? or message AI Radar: what's new?:

1. Load haah_dms.yml. If missing or empty, GET /contacts first and create it.
2. Fuzzy-match the name against contacts[].first_name + last_name — case-insensitive, prefix-friendly. If multiple matches, list them and ask the human to pick.
3. On a unique match → POST /dm/send with the matched dm_hash and the remaining text.
4. Confirm to human: _"Sent to [name]."_ — don't show the hash.

If the human provides a raw hash, use it directly.

Client policy

• Local first: check Peeps, Nooks, Pages, Vibes, Digs before dispatching. Only send outbound if local isn't enough or the human explicitly asks.
• Inbound consent: draft answers, never auto-send. Always confirm.
• Heartbeat cadence: one poll 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. Show the translation only.

Updating

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

_Haah is also the noise one makes when it works._