Govern · Host 接入

描述 Host Runtime

Host Runtime Registration 是建立或更新 Govern bot profile 的版本化 bootstrap envelope。它讓 host 把自有 profile data 與 capability configuration 帶進 Tonetify，不必把特定 domain behavior 寫進運行時核心。

契約狀態

v1 JSON 格式與中性 fixtures 已經落地。目前支援的路徑是匯入 artifact，再轉成以 PostgreSQL 為準的 BotProfile；尚未提供公開的 self-service registration API 或正式 SDK。

Registration 只負責設定運行時。它不會呼叫 Host Tool、建立 proposal、授予 authority 或執行 mutation。

最小 Envelope

{
  "kind": "host_runtime_registration",
  "contract_version": "v1",
  "host": "example_host",
  "bot_profile": {
    "id": "operations_assistant",
    "display_name": "Operations Assistant",
    "persona": "operations-reviewer",
    "fallback_reply": "Not enough host context.",
    "followup_prompt": "Review another proposal?",
    "runtime_mode": "tool_agent_bot"
  },
  "capabilities": {}
}

bot_profile 也能攜帶 host-owned persona、system prompt、demo copy、rules、knowledge、runtime mode 與 model configuration。如果 profile 內沒有對應欄位，則會繼承 top-level demo、rules 與 knowledge。

具有 URL 的 Capability

帶有非空 url 的 capability，可以轉成同名 tool binding：

{
  "capabilities": {
    "event_advisor": {
      "name": "event_advisor",
      "version": "1",
      "url": "https://host.example/api/tonetify/tools/event_advisor",
      "api_key_env": "HOST_TONETIFY_API_KEY"
    },
    "action_proposal_sink": {
      "url": "https://host.example/api/tonetify/action-proposals",
      "api_key_env": "HOST_TONETIFY_API_KEY"
    }
  }
}

新增 capability 不會自動產生行為，必須由 runtime mode 或 adapter 明確使用。

Secret 邊界

Registration 文件不能放 plaintext api_key，契約會拒絕這種輸入。請改用 environment-backed setup input，或經過加密的 host credential registration path。

Tool registration 完成後，binding 會透過 credential_id 指向加密的 HostCredential record；profile content 不會保留明文 key。

Identity 邊界

Tonetify workspace 與 host tenant 是兩種不同 identity。Runtime context 會把 host-owned tenant 放在 host_context：

{
  "runtime_context": {
    "organization_slug": "tonetify-workspace",
    "host_context": {
      "organization_slug": "host-tenant"
    }
  }
}

新的 integration 應使用 host_context.organization_slug 作為 host identity。host_organization_slug 是 compatibility field；單獨的 organization_slug 屬於 Tonetify workspace。

驗證與替換

• kind 必須是 host_runtime_registration。
• Stable fixtures 使用 contract_version: "v1"。
• 具有 URL 的 capability 必須先解析成有效 binding，才能被呼叫。
• 重新匯入時，可以替換指定 profile 的 host-owned configuration。
• Host-specific prompt 與 business policy 仍是 registration data，不會變成 Tonetify core behavior。

下一步：實作版本化 Host Tool。