Govern · Host integration

Implement a versioned host tool

A host tool gives Govern fresh, host-owned facts through a pinned request and response schema. Tonetify calls the registered URL from its server runtime; the tool is not exposed directly to browsers or models.

HTTP boundary

The current adapter sends POST with JSON. When a credential is configured, it adds:

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

The host should authenticate the key, map host_context to its own tenant, validate the idempotency key, and return one schema-valid 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": {}
  }
}

Keep correlation_id stable for one business flow. Preserve causation_id from the immediate upstream event. Reuse idempotency_key when retrying the same logical tool call.

Response effects

The response must match the output schema pinned for the tool version. The current tool-agent runtime understands three normalized effects.

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 belong inside proposal.payload or proposal.context_snapshot. Tonetify stores them without claiming their business meaning.

Host handler responsibilities

1. Authenticate the bearer credential and resolve the host tenant.
2. Treat the request as untrusted input even though it came from Tonetify.
3. Re-read current business state instead of trusting stale event data.
4. Apply host eligibility, budget, targeting, and duplicate rules.
5. Return exactly one allowed effect matching the pinned output schema.
6. Reconcile retries by idempotency_key without duplicating host-side work.

Failure behavior

Malformed output becomes a structured tool error and must not create a proposal. A binding with an unknown or sunset version is rejected before the host action path continues. Deprecated versions may run with a warning trace.

Transport failure does not give Tonetify permission to invent a result. The turn records the error; the host remains the source of business truth.

Next: receive and reconcile proposals.