Govern · Host 接入

實作版本化 Host Tool

Host Tool 透過固定的 request 與 response schema，把最新的 host-owned facts 提供給 Govern。Tonetify 從 server runtime 呼叫已註冊的 URL；Tool 不會直接暴露給 browser 或 model。

HTTP 邊界

目前的 adapter 使用 POST 傳送 JSON。設定 credential 後，會附上：

Authorization: Bearer <host-api-key>
Content-Type: application/json

Host 應驗證 key、把 host_context 對應到自己的 tenant、檢查 idempotency key，並回傳一個符合 schema 的 effect。

Request Envelope

{
  "contract_version": "v1",
  "tool": {
    "binding_id": "event_advisor",
    "name": "event_advisor",
    "version": "1"
  },
  "runtime_context": {
    "organization_slug": "tonetify-workspace",
    "host_context": {
      "organization_slug": "host-tenant"
    },
    "bot_profile_id": "profile-id"
  },
  "correlation_id": "source-event-id",
  "causation_id": "upstream-cause-id",
  "idempotency_key": "host:event:123",
  "input": {
    "input_kind": "event",
    "payload": {},
    "source": {},
    "system_prompt": "",
    "model_config": {}
  }
}

同一個 business flow 應保持相同的 correlation_id；causation_id 應沿用上一個直接觸發此流程的 event。重試同一筆 logical tool call 時，必須重用 idempotency_key。

Response Effect

Response 必須符合指定 tool version 的 output schema。目前 tool-agent runtime 能理解三種標準化 effect。

Proposal：

{
  "effect": "proposal",
  "proposal": {
    "kind": "event_reminder",
    "title": "Review this reminder",
    "body": "The host found one eligible reminder candidate.",
    "payload": {},
    "context_snapshot": {}
  }
}

Reply：

{
  "effect": "reply",
  "body": "No operator action is required."
}

No operation：

{
  "effect": "noop",
  "reason": "not_eligible"
}

Domain fields 應放在 proposal.payload 或 proposal.context_snapshot。Tonetify 會保存這些資料，但不會宣稱理解其業務意義。

Host Handler 的責任

驗證 bearer credential，並解析 host tenant。
即使 request 來自 Tonetify，仍將其視為不可信輸入。
重新讀取目前的 business state，不直接相信可能過期的 event data。
套用 host eligibility、budget、targeting 與 duplicate rules。
只回傳一個符合固定 output schema 的 allowed effect。
依 idempotency_key 處理重試，不重複產生 host-side work。

失敗行為

格式錯誤的 output 會成為 structured tool error，而且不能建立 proposal。Binding 使用未知或 sunset version 時，會在進入 host action path 前被拒絕；deprecated version 可以執行，但會留下 warning trace。

Transport failure 不會讓 Tonetify 有權自行推測結果。Turn 會記錄 error，host 仍是 business truth 的來源。

下一步：接收並同步提案狀態。