Slack runtime readiness

Slack runtime readiness v1

Available in mithai 0.23.26. The embedded API exposes GET /api/runtime-readiness so a host can distinguish an HTTP listener from an initialized Slack adapter running the intended connection configuration. /api/stats remains a statistics endpoint and is not a readiness acknowledgement.

Configuration and identity

The host writes optional top-level activation metadata into the same configuration as the Slack credentials and effective allowed_channels:

runtime_activation:
  workspace_id: "workspace-123"
  agent_id: "agent-456"
  connection_id: "connection-789"
  revision: "connection-revision-12"
  generation: "process-start-34"
adapter:
  type: slack_http
  slack_http:
    managed: true
    bot_token: ${SLACK_BOT_TOKEN}
    signing_secret: ${SLACK_SIGNING_SECRET}
    allowed_channels: [C0123456789]

All five identity fields are required when the object is present. They must be nonblank strings with environment references resolved; malformed or partial metadata fails configuration validation. Values are opaque and are not trimmed or otherwise normalized. The host generates them; tenant inputs and probe query parameters must not supply them.

revision identifies the committed connection configuration and credentials. generation identifies one process start: the host must create a fresh generation for every restart, even when the revision is unchanged. The engine snapshots the loaded metadata; it does not reload identity when the config file changes. Changing the allowlist or credentials requires a new process and matching metadata.

Omitting runtime_activation (or setting it to null) preserves legacy startup, statistics, event delivery, and onboarding. It never yields an affirmative correlated acknowledgement.

Request and response

Use the embedded API’s MITHAI_UI_SOCKET or MITHAI_UI_PORT transport and send Authorization: Bearer <MITHAI_UI_TOKEN>. The route requires bearer authentication; dashboard cookies and query tokens do not authorize it. Missing/incorrect bearer tokens return 401. If API authentication is unconfigured or unresolved, the route returns 503 with {"version":1,"ready":false}.

After initialization, the response is HTTP 200 with Cache-Control: no-store:

{
  "version": 1,
  "workspace_id": "workspace-123",
  "agent_id": "agent-456",
  "connection_id": "connection-789",
  "revision": "connection-revision-12",
  "generation": "process-start-34",
  "ready": true
}

Before initialization or after stop/failure, an authenticated probe returns HTTP 503 with the same loaded identity and ready:false. Without activation metadata it returns only {"version":1,"ready":false}. A missing Slack adapter also returns 503. Query parameters never alter the identity returned.

The host must require HTTP 200, version:1, ready:true, and exact matches for all five expected identity fields. A response for an old revision or generation must not activate the current connection. Treat 404 from older engines, 503, authentication failures, timeouts, and malformed responses as not ready; do not fall back to /api/stats or Slack auth.test.

Lifecycle and membership ordering

Readiness requires an adapter constructed with the effective allowlist, installed message/event/action handlers, and completed transport initialization:

• Managed HTTP: the Bolt request handler is installed. The embedded HTTP listener alone does not establish readiness. Stopped adapters reject forwarded events with 503.
• Standalone HTTP: uvicorn startup must complete successfully after the Bolt handler and routes are installed.
• Socket Mode: after handler registration, the SDK must confirm an active connection. Initial connection or handshake failures remain not ready while the SDK retries; stopping cancels the wait without releasing membership work. An empty allowlist intentionally opens no Socket Mode connection and remains not ready until stopped. This avoids stealing events from other agents sharing the app token.
• Empty managed/standalone HTTP allowlist: initialization may be ready, but the empty allowlist still rejects all channels and triggers no startup membership work. Readiness does not grant channel access.

Startup onboarding and queued join-event onboarding wait for their own adapter’s readiness. Stop or startup failure wakes waiters without running membership work; cancellation is rechecked between blocking lookups, joins, intro generation and posting. Already in-flight calls cannot be recalled. An adapter is single-use; a replacement process must construct a new adapter rather than restart a stopped instance.

Readiness does not wait for membership or private-channel invitations. The host may invite the bot after the matching acknowledgement; missing private membership must not block the probe. This is an initialization signal, not a continuous Slack connectivity probe or evidence that any message has been processed.

In local multi-agent mode the endpoint describes the Slack adapter selected for the embedded API’s default/trigger engine, not every adapter in the process. A host using this activation protocol should launch one managed agent per process and put that agent’s identity at the top level.

Rollout

This ships in 0.23.26, published by the coordinated release PR after merge and successful release checks. No deployment or workflow changes are required for the engine protocol.

Deploy the engine release before enabling the host consumer in last9/multi-mithai#172. That host integration must generate the fields above with the committed configuration, rotate generation for every launch, compare every returned identity field, and perform private-channel invitations only after matching readiness. Existing last9/last9#12096 product consumers receive activation results through the host; no product UI changes are required in this engine repository. End-to-end rollout validation requires the host integration and a Slack workspace with public and private test channels.