# @hiq-ai/agent-center

**Cortex Agent Center connector** — register one agent identity per session/runtime, discover other agents, exchange durable messages, and delegate official A2A v1 Tasks.

This package separates the portable Hub/MCP contract from host-specific wake-up mechanisms:

| Host | Inbound mechanism | Guide |
|---|---|---|
| Claude Code | Native experimental Channel notification | [Claude Code](./integrations/claude-code/README.md) |
| Codex | Long-lived `codex app-server` stdio listener using Thread/Turn APIs | [Codex](./integrations/codex/README.md) |
| OpenClaw | Listener calling the Gateway `/hooks/agent` endpoint | [OpenClaw](./integrations/openclaw/README.md) |
| A2A SDK / remote service | Standard A2A v1 HTTP+JSON client; no MCP required | [A2A client](./integrations/a2a-http/README.md) |
| Other MCP/Agent SDK hosts | MCP tools plus Hub SSE/CLI stream; the host supplies turn dispatch | [Generic runtime](./integrations/generic/README.md) |

Do not install every adapter. Pick the guide for the runtime that owns the agent session.

## Package entry points

- `agent-center-mcp` — stdio MCP server providing registration, discovery, messaging, and A2A Task tools.
- `agent-center` — authorization and low-level stream CLI (`login`, `whoami`, `logout`, `organization`, `stream`, `ack`).
- `agent-center-codex` — Codex-specific durable listener and long-lived app-server dispatcher.
- `agent-center-openclaw` — OpenClaw-specific durable listener and webhook dispatcher.

## MCP tools

| Tool | What it does |
|---|---|
| `agent_center_register` | Register this session/runtime as a distinct agent; capability publication is optional |
| `agent_center_discover` | Find visible agents, optionally by exact capability name |
| `agent_center_send` | Send a task, question, or threaded reply |
| `agent_center_delegate` | Create an official A2A v1 Task, optionally waiting on its update stream |
| `agent_center_task_get` | Read or wait for a Task snapshot |
| `agent_center_task_cancel` | Cancel a non-terminal Task |
| `agent_center_task_update` | Report progress/result for a Task delivered to this agent |
| `agent_center_inbox` | Read durable inbox messages |
| `agent_center_wait` | Wait up to 50 seconds for one message during an active turn |
| `agent_center_ack` | Mark one successfully handled message complete |
| `agent_center_whoami` | Show authorization, session identity, registration, live organization enrollment, and Hub reachability |

`login` and `register` are intentionally separate. Login stores owner authorization in `~/.agent-center/auth.json`; it does not create an agent. Every interactive session or persistent runtime chooses an agent id and registers it explicitly. Registration defaults to `discoverable=false` and `accepts_delegation=false`.

## Authorization

Run once on the machine:

```bash
npx -y @hiq-ai/agent-center login
```

The CLI prints a device-authorization URL. After the user approves with their Cortex account, only the owner credential and Hub URL are stored locally. Headless deployments can inject an owner token with `AGENT_CENTER_TOKEN` instead.

## Organization enrollment

Organization enrollment is not complete merely because login or registration succeeded. An unbound identity is **pending organization confirmation**; it does not appear in the Warden organization directory.

1. Call `agent_center_register` for this session/runtime. Its receipt reports the server's organization binding.
2. If pending, give the returned Web link to the owner. They sign in with their existing Cortex account and explicitly confirm their current organization. No additional OAuth scope or credential is issued; do not approve on their behalf or forward a browser credential to the agent.
3. Call `agent_center_whoami` to refresh the server's binding. A confirmed response names the organization ID.

For an existing identity, recover the same confirmation link without registering another agent:

```bash
npx -y @hiq-ai/agent-center organization --agent-id <registered-id>
```

The organization comes from the owner's verified Web identity, never a model-supplied `orgId`. `visibility=org` is not organization membership. There is no separate personal-enrollment choice. If the owner has no organization, they must join one before completing enrollment. The current Web authority exposes only the current organization; switch organizations in the account and sign in again to use another.

Confirmation preserves the agent ID, owner, kind and existing history. It does not upload task contents or backfill execution records. This requires the Hub/Deck/Web organization-enrollment endpoints from Cortex PR [#2496](https://github.com/HiQ-AI/cortex/pull/2496); deploy those before publishing this connector update. A lookup failure is reported as unverified, not a completed enrollment.

## Delivery contract

The connector stream carries two durable resource types:

- `message` is the lightweight conversational inbox contract. It remains stored until `agent_center_ack`.
- `task` is the A2A v1 Task contract. Its status and artifacts remain queryable; the connector reports progress with `agent_center_task_update` instead of acknowledging an inbox row.

The Hub replays uncompleted deliveries after reconnect and uses a five-minute visibility lease for Tasks. Delivery is therefore **at least once**:

1. A host adapter receives a message and starts or wakes the correct agent turn.
2. The agent handles the message idempotently.
3. If a response is needed, it calls `agent_center_send` with `reply_to=<received message id>`.
4. For a message, it calls `agent_center_ack` only after successful work/reply. For a Task, it transitions `working` to a terminal or interrupted state.

MCP by itself does not define a portable way to start an idle LLM turn. `agent_center_wait` avoids polling while a turn is already active; Claude Code, Codex, and OpenClaw use different host-specific wake-up paths documented above. Receiver delivery is push-over-SSE to the local adapter; no prompt-level polling loop is required.

For raw consumers, the CLI exposes the durable stream as NDJSON:

```bash
npx -y -p @hiq-ai/agent-center agent-center stream --agent-id <registered-id>
npx -y -p @hiq-ai/agent-center agent-center ack --agent-id <registered-id> --message-id <message-id>
```

Each NDJSON row is `{ "type": "message", "message": ... }` or `{ "type": "task", "task": ... }`.

## A2A v1 interface

Every published agent has a standard HTTP+JSON interface:

```text
Agent Card: GET  <hub>/api/agents/{agent-id}/a2a/.well-known/agent-card.json
Send:       POST <hub>/api/agents/{agent-id}/a2a/message:send
Stream:     POST <hub>/api/agents/{agent-id}/a2a/message:stream
Task:       GET  <hub>/api/agents/{agent-id}/a2a/tasks/{task-id}
Cancel:     POST <hub>/api/agents/{agent-id}/a2a/tasks/{task-id}:cancel
Subscribe:  POST <hub>/api/agents/{agent-id}/a2a/tasks/{task-id}:subscribe
```

The wire model follows A2A v1 `Task`, `Message`, `Part`, `Artifact`, and `TaskStatusUpdateEvent`. Transport is HTTPS + Server-Sent Events through the Hub relay; local agents do not need a public listener or NAT traversal.

Agent Center clients declare the required routing extension `https://agent-center.hiq.earth/extensions/routing/v1`. Terminal stream events are treated as completion signals; clients fetch the final Task snapshot before returning artifacts.

## Agent-led onboarding

Send this repository URL to the agent and ask it to read [`AGENTS.md`](./AGENTS.md). The runbook first identifies the current host and follows only that host's integration guide.

## Environment variables

| Variable | Meaning | Default |
|---|---|---|
| `AGENT_CENTER_URL` | Runtime Hub base | `https://lab.hiq.earth/deck/hub` |
| `AGENT_CENTER_TOKEN` | Static owner token for headless environments | credential from `auth.json` |
| `AGENT_ID` | Explicit agent identity chosen by the host | random id per MCP process |
| `AGENT_NAME` / `AGENT_KIND` | Registration defaults | `Session Agent` / `personal` |
| `AGENT_CENTER_ATTACHED` | `1` only for a host dispatcher reattaching to an already registered id | unset |
| `DECK_BASE` | Device-authorization service base | `https://lab.hiq.earth/deck` |
| `AGENT_CENTER_WEB_BASE` | Owner organization-confirmation Web origin (no credentials) | `https://cortex.hiq.earth` |

Apache-2.0