Skip to main content
StageWhisper speaks a protocol that any AI assistant can implement to receive reasoning jobs and return results. This page describes the contract.

​
Architecture

StageWhisper Desktop (E2EE) ↔ StageWhisper Backend (blind relay) ↔ AI Assistant Plugin
The desktop encrypts analysis prompts. The backend routes encrypted envelopes to the paired assistant. The assistant decrypts, reasons, encrypts the result, and posts it back. The backend never sees plaintext content in BYO mode.

​
Reasoning channel

The reasoning channel is request/response:
  1. A ReasoningJob is created by the backend and published to the assistant_channel pubsub topic for the integration.
  2. The assistant plugin subscribes to an SSE stream and receives the job envelope.
  3. The plugin executes the reasoning (via local LLM, remote API, or subagent).
  4. The plugin posts the result back to the backend’s reasoning job completion endpoint.

​
Envelope shape

{
  "event_type": "reasoning_job",
  "job_id": "uuid",
  "purpose": "live_analysis | session_summary | capability_probe",
  "deadline_at": "ISO 8601",
  "schema_version": 1,
  "envelope_version": 1,
  "response_schema": { "...": "JSON Schema" },
  "payload": { "...": "request payload" },
  "provider_kind": "openclaw | hermes"
}

​
BYO encryption

When the job is BYO-encrypted, the payload contains a BYOEnvelope with ciphertext and nonce fields. The plugin decrypts using the XChaCha20-Poly1305 key derived from the X25519 key exchange performed during pairing.

​
SSE stream

The plugin connects to GET /api/v1/openclaw/integrations/{id}/stream with the relay token as Bearer auth. Events are delivered as Server-Sent Events.

​
Heartbeat

The plugin posts heartbeat updates to /api/v1/openclaw/integrations/{id}/heartbeat every 30 seconds, carrying host status and capability information.

​
Capability probe

When the backend sends a reasoning job with purpose: "capability_probe", the assistant self-describes its available skills and returns a capability profile. This is displayed in the desktop assistant settings.

​
Providers

StageWhisper’s provider registry maps provider_kind values (e.g., openclaw, hermes) to descriptors with install commands, pairing instructions, and protocol version requirements. Each provider implements the same envelope contract. Current providers: OpenClaw, Hermes (coming soon).