Hooka Telepathy and A2A

Telepathy is Hooka's actor-to-actor communication feature, built on the generic internal conversation layer. Agents are just one actor kind. Telegram, webhooks, and topics remain notification adapters; they are not required for Telepathy.

Native Model

• actors: participants such as agents, humans, services, and adapters.
• conversations: dm or group rooms with member roles.
• conversation_messages: append-only structured messages.
• actor_inbox: fanout index for efficient actor streams.
• conversation_tasks, task_artifacts, and task_events: A2A task state and ordered task update streams.

Native API

Create an actor:

hooka token-create --name researcher --can-publish=true --can-read=true --topic-pattern '*'
hooka actor-create --id researcher --name Researcher --kind agent --token-id 123

Create a DM or group:

hooka telepathy-create \
  --kind dm \
  --members researcher:member,implementer:member \
  --title "Research handoff"

Send and read messages:

hooka telepathy-send "$TELEPATHY_ID" --text "Please inspect the failing tests."
hooka telepathy-messages "$TELEPATHY_ID" --limit 20
hooka actor-stream researcher

Telepathy messages do not require topic routes, Telegram configuration, or TELEGRAM_DEFAULT_CHAT_ID.

A2A Facade

Hooka exposes A2A without naming native APIs after agents:

• GET /.well-known/agent-card.json
• GET /actors/{actor_id}/a2a/agent-card.json
• POST /actors/{actor_id}/a2a/rpc

The JSON-RPC endpoint requires:

A2A-Version: 1.0
Authorization: Bearer <actor-bound-token>

Supported v1.0 methods:

• SendMessage
• GetTask
• CancelTask
• SubscribeToTask

Example:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-1",
      "role": "ROLE_USER",
      "parts": [
        { "text": "Summarize the repo health.", "mediaType": "text/plain" }
      ]
    },
    "configuration": {
      "returnImmediately": true,
      "historyLength": 10
    }
  }
}

Runtime status/artifact updates can be posted by the target actor:

curl -sS -X POST "$HOOKA_URL/telepathy/$TELEPATHY_ID/tasks/$TASK_ID/events" \
  -H "Authorization: Bearer $TARGET_ACTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"status","state":"working","text":"Started."}'

SubscribeToTask returns Server-Sent Events. Each data: item is a full JSON-RPC response whose result contains task, statusUpdate, or artifactUpdate.

Compatibility Notes

• Hooka targets A2A 1.0 JSON-RPC method names, for example SendMessage and GetTask.
• Empty or missing A2A-Version is rejected as unsupported because the A2A v1.0 spec treats empty version as legacy 0.3.
• Telepathy IDs are the native conversation IDs; wire JSON still uses conversation_id for compatibility.
• A2A contextId maps to Hooka conversation_id.
• A2A taskId maps to conversation_tasks.id.
• A2A Message.parts[] are stored in structured payload and converted to text for the native conversation body.
• Signature and public-key fields are stored for future trust/escrow work, but v1 authentication is still Hooka bearer-token based.