Extend

Component and protocol reference

Extend Sleeptalk through registered components and the documented agent contracts.

Choose the integration boundary

Use custom agents to connect an existing program, HTTP service, ACP agent, or Agent Bridge server. Use an installed Python plugin when the integration belongs inside the Sleeptalk process.

Component	Entry point group	Responsibility
Agent	`sleeptalk.agents`	Conversation, tool events, permissions, abort, and the upstream session.
Transport	`sleeptalk.transports`	Audio capture, participant admission, playback, and presentation.
STT	`sleeptalk.stt`	REST or streaming transcription.
TTS	`sleeptalk.tts`	Streaming synthesis and provider cleanup.

Registration and settings

Each installed entry point registers one advertised component. It loads lazily and runs once. Listing names reads package metadata without importing the plugin. Duplicate names and collisions with existing names or aliases raise errors; an extension cannot replace an existing registration.

A registration can pass probe=, an async check that sleeptalk host probe-runtime runs during setup. It must never send a prompt or start user work.

Component settings live in that component's options table and are validated against its declared schema. Unknown keys are rejected, and a private schema cannot reuse common field names such as model or base_url. A custom provider can be configured through registration without appearing in guided setup.

Agent protocols

Contract	Use it for
In-process Python adapter	`warmup`, `respond_streaming`, `respond`, `abort`, and `close`, inside the Sleeptalk process.
Agent Bridge v1	A remote agent over an authenticated WebSocket or TLS connection, with heartbeats, credit, replay, and reconnect.
Agent Bridge Lite	The JSON-lines profile used by `command` agents over stdio.
HTTP turns	One streaming `POST` per turn from the `http` adapter.

A vendor gateway is not automatically an Agent Bridge server. Use its named adapter or implement the public bridge contract deliberately. Capabilities must describe only events and controls the implementation supports.

Runtime speech is signed little-endian int16 PCM, mono, at 48 kHz. Providers decode compressed formats and resample at their own boundary.

Validate an integration

Load and inspect without sending a prompt

sleeptalk adapter test --config /path/to/profile.toml --json

Add --fixture for the starter's test prompts or --live for a few short real prompts, which can spend model tokens. The report keeps protocol correctness, availability, and voice-quality warnings in separate columns.

A capability advertised as supported must pass its contract check. An unsupported capability is skipped with its declared reason. Automated conformance does not replace a real call that tests the microphone, permissions, tools, interruption, and cleanup.

References: component contracts, agent adapter contract, Agent Bridge v1, conformance, in-process Python adapter, and adding a built-in adapter.