message-adapter

Files (1)

• SKILL.md

SKILL.md (first lines)

# メッセージアダプタの作り方

hub にメッセージの新しい種類を通すとき、**発行側と受信側は 1 つの機能の両端**である。片方だけ作ると、もう片方が自己流になるか、解釈が配送層へ漏れる。

```
外部ソース ──▶ 発行側アダプタ ──▶ hub（汎用・data を解釈しない）──▶ 受信側アダプタ ──▶ 利用者
               /ingest/<source>                                    <name>ctl
               方言を吸収して封筒へ                                  data を読んで意味を与える
```

**中心は汎用のまま保つ。** メッセージの保存形式・配送・認可に新しい概念を足さない。用途ごとの知識は両端のアダプタが持つ。

## 最初に決める 2 つ

1. **この用途に発行側は要るか。** 外部システムが送ってくるなら要る。人やエージェントが CLI で直接送るなら不要
2. **この用途に受信側は要るか。** `data` を読んで表示・絞り込み・固有の操作をするなら要る。封筒をそのまま読むだけなら不要

両方不要なら、アダプタを作らずに汎用 CLI（`send` / `fetch` / `ack`）で足りる。**作らない判断を先に検討する。**

## 発行側アダプタ（`/ingest/<source>`）

外部の方言を吸収して hub の封筒へ変換する。hub 側のルートとして実装する。

**やること**

- 入力をスキーマで検証する（zod 等）。文字列は最大長で truncate してから検証を通す
- 署名を検証する（HMAC 等）。検証前にペイロードを信用しない
- `subject`（一覧用の 1 行）と `body`（受け手がそのまま行動できる Markdown）へ render する
- 機械可読な値は `data` へ入れる。`body` に埋め込んで再パースさせない

**やらないこと**

- 送信先の決定をアダプタ内にハードコードしない。設定（環境変数）から読む
- 変換に失敗したメッセージを黙って捨てない。理由をログへ出し、非 2xx を返す

**実装の参照**: `agent-inbox-hub` の `apps/api/src/routes/ingest-manako.ts`

## 受信側アダプタ（`<name>ctl`）

hub から取得したメッセージを、特定の用途として読む。独立した CLI として実装する。

### 純粋なフィルタにする

`<name>ctl render` は**標準入力の JSON を読み、標準出力へテキストを出すだけ**にする。

- ネットワークへ接続しない
- ファイル状態（キャッシュ・カーソル）を持たない
- 環境変数が無くても動く

得られるもの: テストが入出力の対応だけで書ける。キャッシュとの責務が分かれる。

**検証方法**（実際に測る）:

```bash
printf '[]' > /tmp/empty.json
env -u <HUB>_URL -u <HUB>_API_KEY <name>ctl render < /tmp/empty.json; echo "exit=$?"
```

認証情報が無い状態で exit 0 になること。ならなければネットワークかファイルに触れている。

### 書き込みは transport CLI を子プロセスで呼ぶ

送信・ack を自前で実装しない。認証・HTTP・リトライ・タイムアウトは transport 側に閉じる。

```
<name>ctl <操作> <id>
  → aih ack <id>                              1 手目
  → aih send --reply-to <id> --data '{...}'   2 手目
```

**運用操作は transport プリミティブの合成として設計する。** 1 つの操作を 2 手以上へ分解できるなら、それがアダプタを立てる動機になる。

失敗時は理由を標準エラーへ出して非 0 で終了する。transport CLI が PATH に無い場合も同様。

### 状態は呼び出し側が持つ

キャッシュ・カーソル・重複排除の記録はアダプタではなく呼び出し側（hook 等）が持つ。

**キャッシュは整形前の JSON を保存する。** 整形後のテキストを保存すると、表示を変えるたびに過去のキャッシュが無効になる。到達不可は transport の問題であって解釈の問題ではない。

## 境界の判断基準

| 対象 | 置き場所 |
|---|---|
| 封筒（`id` / `from` / `to` / `createdAt` 等）の整形 | transport 側（共有パッケージ） |
| `data` の中身を読んで意味を与える整形 | アダプタ |
| 認証・HTTP・リトライ・タイムアウト | transport 側 |
| キャッシュ・カーソル・セッション固有の状態 | 呼び出し側 |

**この線を文書に明記する。** 書かないと、将来「整形を 1 箇所へ集約する」というリファクタが層を元へ戻す。

## 踏んだ罠

### 解釈が配送層へ漏れる

安全性の指摘へ最短で対応しようとすると、表示を hook へ足したくなる。動くが、配送層が `data` のキー名と既定値を知ることになる。

**検査**: 配送層に用途固有の語彙が無いことを grep で機械的に確かめる。

```bash
grep -n '<用途固有のキー名>' <配送層のファイル>   # 0 件であること
```

### 整形が重複する

アダプタが JSON を受けてテキストを出す以上、封筒部分も出力に含まれる。対策しなければ transport 側と同じ整形をもう 1 つ書くことになる。

**対策**: 封筒整形の実装を共有パッケージへ集約し、行の配列を返す関数に分ける。アダプタはその行間へ固有の 1 行を挿入する。共有側に拡張点（コールバック等）を持たせない——持たせると共有側が用途を知る。

### 新しい実行ファイルは配布とセットで完成する

コードを書いてマージしても、配布手順を更新しなければ利用者の環境で動かない。

セットアップ手順に次を追加する。

- build と PATH への配置
- 更新手順（transport CLI と同時に build する。片方だけ古いと壊れる）
- **実体確認**（`command -v` だけで終わらせず、実際に実行して exit 0 を確認する）

From elchika-inc/agent-toolkit, MIT.

More from elchika-inc/agent-toolkit