Govern · Host integration

Describe a host runtime

A host runtime registration is a versioned bootstrap envelope for creating or updating a Govern bot profile. It carries host-owned profile data and capability configuration into Tonetify without adding host-specific behavior to the runtime core.

Contract status

The v1 JSON shape and neutral fixtures are landed. The current supported path is an import artifact that becomes a PostgreSQL-backed BotProfile; there is no public self-service registration API or supported SDK yet.

Registration configures the runtime. It does not call a host tool, create a proposal, grant authority, or execute a mutation.

Minimal 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 may also carry host-owned persona, system prompt, demo copy, rules, knowledge, runtime mode, and model configuration. Top-level demo, rules, and knowledge are inherited when the corresponding profile fields are absent.

URL-backed capabilities

A capability with a non-empty url may become a tool binding with the same key:

{
  "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"
    }
  }
}

Adding a capability does not create behavior by itself. A runtime mode or adapter must explicitly consume it.

Secret boundary

Do not put plaintext api_key values in a registration document. The registration contract rejects them. Use environment-backed setup input or the encrypted host-credential registration path.

After tool registration, bindings reference encrypted HostCredential records by credential_id; profile content does not retain the plaintext key.

Identity boundary

The Tonetify workspace and the host tenant are different identities. Runtime context keeps the host-owned tenant under host_context:

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

New integrations should use host_context.organization_slug for host identity. host_organization_slug is a compatibility field; bare organization_slug belongs to the Tonetify workspace.

Validation and replacement

• kind must be host_runtime_registration.
• Stable fixtures use contract_version: "v1".
• A URL-backed capability must resolve to a valid binding before it can be invoked.
• Re-import may replace host-owned profile configuration for the selected profile.
• Host-specific prompts and business policy remain registration data, not Tonetify core behavior.

Next: implement a versioned host tool.