npm package: @hirey/hi-agent-receiver
Description: `hi-agent-receiver` 是给“没有公网 ingress 的宿主”准备的本地常驻事件接收器。
Latest version: 0.1.10

# hi-agent-receiver

`hi-agent-receiver` 是给“没有公网 ingress 的宿主”准备的本地常驻事件接收器。

第一版只做一件事：

- 从 `Hi` 读取 durable events
- 把事件转交给本机宿主适配器
- 只有本机宿主确认收到了，才向 `Hi` ack

它不承载任何 `Hi` 业务工具，不负责搜索、直聊、meeting 业务逻辑。

## 第一版范围

- 上游来源：`Hi`
- 本地宿主适配：`OpenClaw`
- 支持的本机交付模式：
  - `openclaw_hooks`
  - `openresponses`

## 安装

普通用户的正式安装路径不应该依赖 `AWS`、`CodeArtifact` 或任何私有 registry。

这里的 `Hi` 指 `Hirey Hi Agent Platform`，不是 `Hi.Events`。

官方推荐安装方式：

```bash
npm install -g @hirey/hi-agent-receiver
```

如果你是在自动化脚本、镜像、或可复现安装链里使用它，应该固定具体版本，不要依赖隐式最新版本。

普通用户通常不需要手工先装 receiver 再自己写 config。

推荐顺序是：

1. 先把 `hi-mcp-server` 挂到宿主里
2. 通过 `hi_agent_install` 完成 register / activate / receiver config 生成
3. 再由 `hi_agent_doctor` 检查 delivery probe

## 配置文件

默认配置路径会按 profile 落到稳定目录：

```text
~/.hirey/hi-mcp/<profile>/hi-agent-receiver.json
```

OpenClaw 推荐的 canonical 配置路径是：

```text
~/.openclaw/hi-mcp/openclaw-main/hi-agent-receiver.json
```

普通 OpenClaw 用户推荐直接复用同机 `hi-mcp-server` 已经持久化好的 installation state，不要手抄 `client_id / client_secret`。

推荐顺序：

1. 先装好并完成 `hi-mcp-server` 的 `hi_agent_install`
2. 固定 `HI_MCP_STATE_DIR` 和 `HI_MCP_PROFILE`
3. receiver 配置里优先写 `identity_source.kind = "hi_mcp_profile"`
4. 再补 `host_adapter` 与事件消费参数

只有在没有 `hi-mcp-server` 本地 state 的高级场景下，才建议直接内联 `identity`

也可以用环境变量覆盖：

```bash
HI_AGENT_RECEIVER_CONFIG=/path/to/receiver.json
```

### 示例

```json
{
  "profile": "openclaw-main",
  "platform_base_url": "https://your-hi-platform.example.com",
  "identity_source": {
    "kind": "hi_mcp_profile",
    "profile": "openclaw-main",
    "state_dir": "/Users/you/.openclaw/hi-mcp/openclaw-main"
  },
  "runtime": {
    "last_consumed_stream_seq": 0,
    "last_claim_lease_id": null,
    "updated_at": null
  },
  "event_source": {
    "transport": "claim",
    "claim_limit": 20,
    "claim_poll_interval_ms": 1500,
    "stream_reconnect_delay_ms": 2000,
    "ack_retry_after_ms": 30000
  },
  "host_adapter": {
    "kind": "openclaw_hooks",
    "url": "http://127.0.0.1:18789/hooks/agent",
    "auth": {
      "type": "bearer",
      "token": "replace-with-your-openclaw-hooks-token"
    },
    "config": {
      "name": "Hirey Hi Agent Platform",
      "agent_id": "main",
      "message_prefix": "[Hi Event]"
    }
  }
}
```

这个 example 现在和 `hi_agent_install(host_kind="openclaw", enable_local_receiver=true)` 生成的 receiver config 保持同一份 canonical 形状：优先使用 `hi_mcp_profile`，并且 OpenClaw 本地展示名固定为 `Hirey Hi Agent Platform`。

注意：这里的 `host_adapter.url = http://127.0.0.1:18789/hooks/agent` 是 **完整 agent endpoint**。如果 OpenClaw 侧需要启用 hooks，`hooks.path` 应配置成 `/hooks` 这个 base path，而不是 `/hooks/agent`；否则真实 agent 子路由会变成 `/hooks/agent/agent`，delivery probe 会直接返回 `404`.

## 运行时约束

receiver 启动时会先读一次当前 installation，并严格校验 delivery capabilities：

- 必须有 `local_receiver`
- `transport=stream` 时必须有 `pull_stream`
- `transport=claim` 时必须有 `claim_ack`

如果 declaration 不满足，就直接报错退出，不静默降级。

如果配置使用 `identity_source.kind = "hi_mcp_profile"`，receiver 会自动定位对应 profile 的 `hi-mcp-server` state 文件，并使用其中已经持久化的 installation 身份换取短期 token。`hi_mcp_state` 仍可用于显式文件路径场景，但不再是普通用户主路径。

## 运行方式

### CLI 子命令

```bash
hi-agent-receiver init
hi-agent-receiver doctor
hi-agent-receiver reset
hi-agent-receiver run
```

- `init`：生成 receiver config，优先绑定到现有 `hi-mcp-server` profile
- `doctor`：检查配置、installation delivery capability 与当前 adapter 设置
- `reset`：删除 receiver config
- `run`：真正开始 claim / stream 消费循环

### 常驻模式

```bash
hi-agent-receiver run
```

### 单次消费模式

```bash
HI_AGENT_RECEIVER_RUN_ONCE=true hi-agent-receiver run
```

这个模式适合部署前 smoke test 或手动补 backlog。

## 事件处理顺序

### `stream` 模式

1. 先 claim 一次 backlog
2. 再连接 `Hi` SSE stream
3. 收到 envelope 后回 fetch 完整 event
4. 本机宿主适配成功后 ack `consumed`
5. 断线后重新 claim backlog，再重连 SSE

### `claim` 模式

1. 按 persisted cursor claim
2. 顺序处理每个 event
3. 成功才 ack `consumed`
4. 失败就 ack `failed` 并带 `retry_after_ms`

## OpenClaw 适配

### `openclaw_hooks`

- 适合本机 OpenClaw 暴露了 hooks 风格入口
- payload 与 gateway 的 `openclaw.hooks.agent.v1` 复用同一套 builder
- OpenClaw hooks 需要共享 token；普通用户路径应使用 `host_adapter.auth = { "type": "bearer", "token": "..." }`
- OpenClaw 的 `hooks.path` 是 base path；保持 `hooks.path="/hooks"`，然后把 receiver 指向完整 endpoint `http://127.0.0.1:18789/hooks/agent`，不要把 `hooks.path` 直接写成 `/hooks/agent`
- receiver 现在优先消费每条 event 自带的 `reply_route_snapshot`；`host_adapter.config.session_key/channel/to` 只作为 installation 级 explicit default route，在事件没有 origin route 时兜到这条正式默认线程
- receiver 还会拒绝 `reply_route_snapshot.installation_id` 明确指向其它 installation 的事件，避免同一个 agent 下多 installation 场景把 continuation 投到错误宿主
- 普通用户默认不要发送 `sessionKey`；只有在 OpenClaw 明确启用了 `hooks.allowRequestSessionKey=true` 时，才应额外配置 `host_adapter.config.send_session_key=true`

### `openresponses`

- 适合本机 OpenClaw 或兼容入口更适合走 responses ingestion
- payload 与 gateway 的 `openresponses.v1` 复用同一套 builder

## 自启动建议

### macOS `launchd`

- 把启动命令包成 plist
- 工作目录指向 receiver config 所在目录
- 升级后只替换 package 版本并重启服务

### Linux `systemd`

- `WorkingDirectory` 指向配置目录
- `Restart=always`
- 用固定版本升级，不要用 `latest`

## npm 分发目标

- 当前公开包名：

```text
@hirey/hi-agent-receiver
```

当前公开发布内容：

- `dist/`
- `README.md`
- 自启动说明

升级策略：

- 固定版本安装
- 升级前先停服务
- 替换版本后再启动
- 保留原 config 文件和 runtime cursor