{"id":47905064,"url":"https://github.com/himkt/hikyaku","last_synced_at":"2026-04-04T04:48:30.016Z","repository":{"id":347689760,"uuid":"1194272239","full_name":"himkt/hikyaku","owner":"himkt","description":"☎️ A2A communication, even for Coding Agent","archived":false,"fork":false,"pushed_at":"2026-03-31T15:35:16.000Z","size":414,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T04:48:29.670Z","etag":null,"topics":["a2a","a2a-protocol","agent","coding-agent","mcp","mcp-server","skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/himkt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T05:56:46.000Z","updated_at":"2026-03-31T15:35:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/himkt/hikyaku","commit_stats":null,"previous_names":["himkt/hikyaku"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/himkt/hikyaku","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fhikyaku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fhikyaku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fhikyaku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fhikyaku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/himkt","download_url":"https://codeload.github.com/himkt/hikyaku/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fhikyaku/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31388168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","a2a-protocol","agent","coding-agent","mcp","mcp-server","skills"],"created_at":"2026-04-04T04:48:28.858Z","updated_at":"2026-04-04T04:48:30.000Z","avatar_url":"https://github.com/himkt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hikyaku\n\nA2A-native message broker and agent registry for coding agents.\n\nHikyaku enables ephemeral agents -- such as Claude Code sessions, CI/CD runners, and other coding agents -- to discover each other and exchange messages using the standard [A2A (Agent-to-Agent) protocol](https://github.com/google/A2A). Agents do not need to host HTTP servers; the broker handles all message routing and storage. Agents are organized into **tenants** via shared API keys -- agents sharing the same key form a tenant and can discover and message each other; agents in different tenants are invisible to one another.\n\n## Features\n\n- **Agent Registry** -- Register, discover, and deregister agents via REST API\n- **Tenant Isolation** -- Shared API key defines a tenant boundary; cross-tenant agents are fully invisible to each other\n- **Unicast Messaging** -- Send messages to a specific agent by ID (same-tenant only)\n- **Broadcast Messaging** -- Send messages to all agents in the same tenant\n- **Inbox Polling** -- Agents poll for new messages at their own pace; supports delta polling via `statusTimestampAfter`\n- **Real-time Inbox Notification** -- SSE endpoint (`/api/v1/subscribe`) pushes new messages as they arrive\n- **MCP Server** -- Transparent proxy for Claude Code and other MCP clients; `poll` returns instantly from SSE-buffered messages\n- **Message Lifecycle** -- Acknowledge, cancel (retract), and track message status\n- **Two-Header Auth** -- API key (tenant) + Agent-Id (identity) required on all authenticated requests\n- **WebUI** -- Browser-based dashboard with Auth0 login; users manage API keys, select tenants, and browse agents and message history\n- **CLI Tool** -- Full-featured command-line client for all broker operations\n\n## Architecture\n\n```\n     Tenant X (shared API key)            +----------------------------+\n    + - - - - - - - - - - - - +           |          Broker            |\n                                          |                            |\n    | +-------------+         |           |  +--------------------+    |\n      |  Agent A     | SendMessage        |  | A2A Server         |    |\n    | |  (sender)    |---------------------\u003e | (tenant-scoped)    |    |\n      +-------------+ Authorization:      |  +--------+-----------+    |\n    |                  Bearer \u003capi_key\u003e   |           |                |\n                       X-Agent-Id: \u003cid\u003e   |           v                |\n    | +-------------+         |           |  +--------------------+    |\n      |  Agent B     | ListTasks          |  | Redis              |    |\n    | | (recipient)  |\u003c-------------------+  | +----------------+ |    |\n      +-------------+         |           |  | | Agent Store    | |    |\n    |                                     |  | | Task Store     | |    |\n     - - - - - - - - - - - - -            |  | | Tenant Sets    | |    |\n                                          |  | | Pub/Sub Chans  | |    |\n     Tenant Y (different API key)         |  | +----------------+ |    |\n    + - - - - - - - - - - - - +           |  +--------------------+    |\n      +-------------+                     |                            |\n    | |  Agent C     | (isolated) |       |  +--------------------+    |\n      | (discovery)  |                    |  | SSE Endpoint       |    |\n    | +-------------+            |        |  | /api/v1/subscribe  |    |\n     - - - - - - - - - - - - -            |  +--------------------+    |\n                                          +----------------------------+\n\n  +---------------+  MCP tools   +--------------------------------------+\n  | Claude Code   |-------------\u003e|  hikyaku-mcp (transparent proxy)     |\n  |  (agent)      |  poll, send, |                                      |\n  |               |  ack, ...    |  +----------+   +----------------+   |\n  +---------------+              |  | Buffer   |\u003c--| SSE Client     |   |\n                                 |  | (Queue)  |   | (background)   |   |\n                                 |  +----+-----+   +-------+--------+   |\n                                 |       | poll            | SSE        |\n                                 |  +----+-----+   +-------+--------+   |\n                                 |  | Registry  |   | /api/v1/       |  |\n                                 |  | Forwarder |   | subscribe      |  |\n                                 |  +----+-----+   +-------+--------+   |\n                                 +-------+------------------+-----------+\n                                         | REST/JSON-RPC    | SSE\n                                         v                  v\n                                 +--------------------------------------+\n                                 |  hikyaku-registry (broker)           |\n                                 +--------------------------------------+\n```\n\nKey design decisions:\n\n- The API key is the tenant boundary. `SHA-256(api_key)` is stored as `tenant_id`. All agents with the same key form one tenant.\n- The `contextId` field is set to the recipient's agent ID on every delivery Task, enabling inbox discovery via `ListTasks(contextId=myAgentId)`.\n- Task states map to message lifecycle: `INPUT_REQUIRED` (unread), `COMPLETED` (acknowledged), `CANCELED` (retracted), `FAILED` (routing error).\n- FastAPI is the ASGI parent; the A2A SDK handler is mounted at the root path. FastAPI routes (`/api/v1/*`) take priority.\n- Tenants are created via WebUI API key management. Revoking a key deregisters all agents and invalidates the tenant. An empty tenant (no agents) remains valid as long as its key is active.\n- The broker exposes three API surfaces: A2A Server (JSON-RPC 2.0), Registry REST API (`/api/v1/`), and WebUI (`/ui/`).\n- The WebUI uses Auth0 for user authentication. Agent-to-broker communication uses API keys (unchanged).\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.12+\n- Redis (running locally or via Docker)\n- [uv](https://docs.astral.sh/uv/)\n- [Auth0](https://auth0.com/) account (for WebUI user authentication)\n\n### Start the Broker Server\n\n```bash\nmise //registry:dev\n```\n\nThe broker will be available at `http://localhost:8000`.\n\n### Install the CLI Client\n\n```bash\ncd client\nuv tool install .\n```\n\n### Create an API Key\n\nLog into the WebUI at `http://localhost:8000/ui/` via Auth0, then create an API key from the key management page. The raw key is shown only once -- save it securely.\n\n### Set Credentials\n\n```bash\nexport HIKYAKU_API_KEY=\"hky_...\"\nexport HIKYAKU_URL=\"http://localhost:8000\"   # optional, defaults to http://localhost:8000\n```\n\n### Register an Agent\n\n```bash\nhikyaku register --name \"my-agent\" --description \"A coding assistant\"\n```\n\nSave the returned `agent_id` for subsequent commands. Registration always requires a valid `HIKYAKU_API_KEY`.\n\n### Send a Message\n\n```bash\nhikyaku send --agent-id \u003cyour-agent-id\u003e --to \u003crecipient-agent-id\u003e --text \"Hello from my agent\"\n```\n\n### Poll for Messages\n\n```bash\nhikyaku poll --agent-id \u003cyour-agent-id\u003e\n```\n\n### Acknowledge a Message\n\n```bash\nhikyaku ack --agent-id \u003cyour-agent-id\u003e --task-id \u003ctask-id\u003e\n```\n\n## CLI Usage\n\nCredentials are set via environment variables:\n\n| Variable | Required | Description |\n|---|---|---|\n| `HIKYAKU_API_KEY` | Yes | API key for tenant authentication |\n| `HIKYAKU_URL` | No | Broker URL (default: `http://localhost:8000`) |\n\nThe `--agent-id` option is a per-subcommand option required by most commands. The global `--json` flag enables JSON output.\n\n| Command | `--agent-id` | Description |\n|---|---|---|\n| `hikyaku register` | Not required | Register a new agent; returns an agent ID |\n| `hikyaku send` | Required | Send a unicast message to another agent in the same tenant |\n| `hikyaku broadcast` | Required | Broadcast a message to all agents in the same tenant |\n| `hikyaku poll` | Required | Poll inbox for incoming messages |\n| `hikyaku ack` | Required | Acknowledge receipt of a message |\n| `hikyaku cancel` | Required | Cancel (retract) a sent message before it is acknowledged |\n| `hikyaku get-task` | Required | Get details of a specific task/message |\n| `hikyaku agents` | Required | List agents in the tenant or get detail for a specific agent |\n| `hikyaku deregister` | Required | Deregister this agent from the broker |\n\n## API Overview\n\n### Authentication\n\n**Agent-to-broker**: All requests require two headers:\n\n| Header | Purpose |\n|---|---|\n| `Authorization: Bearer \u003capi_key\u003e` | Authenticates the tenant (`SHA-256(api_key)` = `tenant_id`) |\n| `X-Agent-Id: \u003cagent_id\u003e` | Identifies the specific agent within the tenant |\n\nAPI keys use the format `hky_` + 32 random hex characters (e.g., `hky_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4`). Keys are created through the WebUI key management interface (requires Auth0 login).\n\n**WebUI**: Auth0 JWT in `Authorization` header. Tenant-scoped endpoints additionally require `X-Tenant-Id` header.\n\n### Registry API (REST)\n\nBase path: `/api/v1`\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| POST | `/api/v1/agents` | Bearer | Register a new agent; API key (created via WebUI) is always required |\n| GET | `/api/v1/agents` | Bearer + Agent-Id | List agents in the caller's tenant |\n| GET | `/api/v1/agents/{id}` | Bearer + Agent-Id | Get agent detail (404 if not in same tenant) |\n| DELETE | `/api/v1/agents/{id}` | Bearer + Agent-Id | Deregister an agent (self only) |\n| GET | `/api/v1/subscribe` | Bearer + Agent-Id | SSE stream for real-time inbox notifications |\n| GET | `/.well-known/agent-card.json` | None | Broker's own A2A Agent Card |\n\nRegistry API errors use a consistent JSON envelope:\n\n```json\n{\n  \"error\": {\n    \"code\": \"AGENT_NOT_FOUND\",\n    \"message\": \"Agent with id '...' not found\"\n  }\n}\n```\n\n| Error Code | HTTP Status | Description |\n|---|---|---|\n| `UNAUTHORIZED` | 401 | Missing or invalid API key, missing `X-Agent-Id`, or agent-tenant mismatch |\n| `FORBIDDEN` | 403 | API key does not match the target resource |\n| `AGENT_NOT_FOUND` | 404 | Agent does not exist, is deregistered, or belongs to a different tenant |\n| `INVALID_REQUEST` | 400 | Missing required fields or invalid values |\n\n### A2A Operations (JSON-RPC 2.0)\n\n| Method | Description |\n|---|---|\n| `SendMessage` | Send unicast (`metadata.destination=\u003cagent-uuid\u003e`) or broadcast (`metadata.destination=*`) |\n| `ListTasks` | Poll inbox -- use `contextId=\u003cown-agent-id\u003e` to retrieve messages addressed to this agent; supports `statusTimestampAfter` for delta polling |\n| `GetTask` | Retrieve a specific message by task ID |\n| `CancelTask` | Retract an unread message (sender only, `INPUT_REQUIRED` state only) |\n\n`ListTasks` enforces that `contextId` must equal the caller's agent ID. Providing a different `contextId` returns an error to prevent inbox snooping.\n\n### Message Lifecycle\n\n| Task State | Meaning |\n|---|---|\n| `TASK_STATE_INPUT_REQUIRED` | Message queued, awaiting recipient pickup (unread) |\n| `TASK_STATE_COMPLETED` | Message acknowledged by recipient |\n| `TASK_STATE_CANCELED` | Message retracted by sender before ACK |\n| `TASK_STATE_FAILED` | Routing error (returned immediately to sender) |\n\n### WebUI API\n\nBase path: `/ui/api`\n\nThe WebUI API is consumed by the browser SPA. Authentication uses Auth0 JWT (`Authorization: Bearer \u003cauth0_jwt\u003e`). Tenant-scoped endpoints require an `X-Tenant-Id` header to select which tenant's data to view.\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| GET | `/ui/api/auth/config` | None | Returns Auth0 domain + client_id for SPA initialization |\n| POST | `/ui/api/keys` | JWT | Create a new API key (raw key shown once) |\n| GET | `/ui/api/keys` | JWT | List API keys owned by the authenticated user |\n| DELETE | `/ui/api/keys/{tenant_id}` | JWT | Revoke an API key and deregister all its agents |\n| GET | `/ui/api/agents` | JWT + Tenant-Id | List agents in the selected tenant |\n| GET | `/ui/api/agents/{id}/inbox` | JWT + Tenant-Id | Inbox messages for an agent (newest first) |\n| GET | `/ui/api/agents/{id}/sent` | JWT + Tenant-Id | Sent messages for an agent (newest first) |\n| POST | `/ui/api/messages/send` | JWT + Tenant-Id | Send a unicast message between two same-tenant agents |\n\nThe WebUI SPA is served as static files at `/ui/`. It is built from `admin/` (Vite + React + TypeScript + Tailwind CSS).\n\n## MCP Server (Claude Code Integration)\n\nThe `hikyaku-mcp` package provides a transparent MCP server proxy. It exposes the same tools as the CLI but `poll` returns instantly from a local SSE-buffered queue.\n\n### Configuration\n\nAdd to your Claude Code `settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hikyaku\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/hikyaku/mcp-server\", \"hikyaku-mcp\"],\n      \"env\": {\n        \"HIKYAKU_URL\": \"http://localhost:8000\",\n        \"HIKYAKU_API_KEY\": \"hky_...\",\n        \"HIKYAKU_AGENT_ID\": \"...\"\n      }\n    }\n  }\n}\n```\n\nThe MCP server auto-connects to the broker's SSE endpoint on startup. All tools (send, broadcast, ack, cancel, get_task, agents, register, deregister) forward to the registry; `poll` drains the local buffer.\n\n## Tech Stack\n\n- **Python 3.12+** with uv workspace\n- **Server**: FastAPI + Redis + a2a-sdk + Pydantic + pydantic-settings\n- **CLI**: click + httpx + a2a-sdk\n- **MCP Server**: mcp + httpx + httpx-sse\n- **WebUI**: Vite + React 19 + TypeScript + Tailwind CSS 4\n\n## Project Structure\n\n```\nhikyaku/\n  pyproject.toml          # Workspace root (uv workspace)\n  registry/               # hikyaku-registry server package\n    src/hikyaku_registry/\n    tests/\n    pyproject.toml\n  client/                 # hikyaku-client CLI package\n    src/hikyaku_client/\n    tests/\n    pyproject.toml\n  mcp-server/             # hikyaku-mcp MCP server package\n    src/hikyaku_mcp/\n    tests/\n    pyproject.toml\n  admin/                  # WebUI SPA (Vite + React + TypeScript + Tailwind CSS)\n  docs/\n    spec/                 # API and data model specifications\n      registry-api.md\n      a2a-operations.md\n      data-model.md\n      webui-api.md\n      streaming-subscribe.md\n      cli-options.md\n  ARCHITECTURE.md         # System architecture and design decisions\n```\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/himkt/hikyaku.git\ncd hikyaku\n\n# Install all workspace dependencies\nuv sync\n\n# Run registry tests\ncd registry\nmise test\n\n# Run client tests\ncd client\nmise test\n\n# Run MCP server tests\ncd mcp-server\nmise test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhimkt%2Fhikyaku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhimkt%2Fhikyaku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhimkt%2Fhikyaku/lists"}