feat(module): own bounded live transport and relay runtime

.github/scripts/check-live-module-coverage.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Exercise native fixtures and the real artifact before checking live-runtime files.
+set -euo pipefail
+minimum="${1:-90}"
+report="${2:-live-module-coverage.json}"
+manifest="crates/tinyvoice-module/Cargo.toml"
+cargo llvm-cov --locked --manifest-path "$manifest" --all-features --lib --no-report
+# all-features selects static-link; the loader needs the default dynamic build.
+cargo llvm-cov run --locked --manifest-path "$manifest" --no-report --example verify_module -- crates/tinyvoice-module/target/llvm-cov-target/debug/deps/libtinyvoice_module.so
+cargo llvm-cov report --manifest-path "$manifest" --json --output-path "$report"
+require_runtime_coverage() {
+  local prefix="$1"
+  local expected="$2"
+count="$(jq --arg prefix "$prefix" '[.data[].files[] | select(.filename | startswith($prefix)) | select(.filename | endswith("_tests.rs") | not) | select(.summary.lines.count > 0)] | length' "$report")"
+if [[ "$count" -ne "$expected" ]]; then
+  echo "expected $expected covered runtime source files under $prefix, found $count" >&2
+  exit 1
+fi
+jq -r --arg prefix "$prefix" '.data[].files[] | select(.filename | startswith($prefix)) | select(.filename | endswith("_tests.rs") | not) | select(.summary.lines.count > 0) | "\(.filename): \(.summary.lines.percent)%"' "$report"
+failures="$(jq -r --arg prefix "$prefix" --argjson minimum "$minimum" '.data[].files[] | select(.filename | startswith($prefix)) | select(.filename | endswith("_tests.rs") | not) | select(.summary.lines.count > 0) | select(.summary.lines.percent < $minimum) | "\(.filename): \(.summary.lines.percent)%"' "$report")"
+if [[ -n "$failures" ]]; then
+  printf 'Runtime files below %s%% line coverage:\n%s\n' "$minimum" "$failures" >&2
+  exit 1
+fi
+
+}
+require_runtime_coverage "$(pwd -P)/crates/tinyvoice-module/src/service/live/" 6
+require_runtime_coverage "$(pwd -P)/crates/tinyvoice-module/src/service/relay_runtime/" 2

.gitmodules

@@ -2,3 +2,6 @@
 	path = vendor/tinybus
 	url = https://github.com/tinyhumansai/tinybus
 	branch = main
+[submodule "vendor/tinyagents"]
+	path = vendor/tinyagents
+	url = https://github.com/tinyhumansai/tinyagents

MODULE.md

@@ -4,7 +4,7 @@ This package contains the native `tinyvoice` module for TinyBus module ABI v1.
 Install only the archive matching the host operating system and architecture.
 
 The module claims `ai.tinyhumans.tinyvoice.Voice`, serves the object at
-`/ai/tinyhumans/tinyvoice/Voice`, and provides 34 methods under contract 1.6.
+`/ai/tinyhumans/tinyvoice/Voice`, and provides 47 methods under contract 1.8.
 
 ## Methods
 
@@ -21,6 +21,19 @@ The module claims `ai.tinyhumans.tinyvoice.Voice`, serves the object at
 | `VadReset` | `session` | — |
 | `VadClose` | `session` | — |
 | `PrepareRelayTurn` | `RelayTurnRequest { messages, readback_prefix }` | `PreparedRelayTurn`: prompt, ordered history pairs, optional readback payload, content-free, speak-back and answerable flags |
+| `PrepareLiveInput` | `PrepareLiveInputRequest { awaiting_start, frame }` | parsed control or transport action; host owns policy validation |
+| `LiveBindTransport` | reserved handle and mechanical host transport port | idempotent `LiveStatus`; module owns the client/provider coordinator |
+| `RelayConfigure` | explicit concurrent/pending turn limits | immutable idempotent `RelayLimits` |
+| `RelayReserve` | none | bounded opaque `RelayStatus` before native work |
+| `RelayStart` | reserved handle, saved host callback context, explicit timing/fallbacks | asynchronous idempotent `RelayStatus` |
+| `RelayRelease` | known relay handle | bounded cleanup and closed status |
+| `RelayShutdown` | none | permanent closed admission and bounded concurrent cleanup |
+| `LiveReserve` | none | opaque `LiveStatus` reserved before connection startup |
+| `LiveStart` | `LiveStartRequest` | idempotent starting/running status for identical inputs |
+| `LiveSend` | handle and text, PCM16 audio, interrupt or stop command | status after bounded input admission |
+| `LiveRead` | handle and optional acknowledged batch | bounded replayable ordered frames and persistence effects |
+| `LiveRelease` | handle | closed status after bounded provider/context cleanup |
+| `LiveShutdown` | none | terminal admission shutdown and concurrent bounded cleanup |
 | `PrepareFrames` | `samples`, `source_rate`, `channels` | base64 `f32` mono @ 16 kHz |
 | `FrameEnergies` | `samples`, `frame_len` | per-frame RMS |
 | `EncodeWav` | `samples` (`f32` mono), `sample_rate` | base64 WAV |
@@ -114,3 +127,5 @@ TinyBus modules are trusted in-process code: a loaded module shares the address
 space, the privileges and the crash domain, and TinyBus never unloads one.
 Install release artifacts only from a trusted source, and restart the host after
 replacing a loaded module.
+
+Relay coordination uses context-bound host callbacks; see the [relay runtime contract](docs/specs/relay-module-runtime.md).

README.md

@@ -29,6 +29,7 @@ permission check.
 | Wake-word gate, intent routing | What to *do* with an intent |
 | Hallucination detection | The STT transport, credentials, and retry policy |
 | Relay user-text extraction, readback classification and turn preparation | Local agent execution, product prompts, acknowledgment timing and delivery |
+| Portable live controls and module-owned provider/socket coordinator | Prepared credentials, provider selection, current tool policy and transcript persistence |
 
 A visible consequence: `VadConfig` has no constructor that reads a config file.
 A host builds one from whatever it persists. A crate that guessed at that shape
@@ -98,6 +99,29 @@ on a realtime thread where blocking causes dropouts, so callbacks forward raw
 interleaved samples into a bounded queue. Hosts poll batches and call
 `PrepareFrames` from a worker.
 
+### Relay turn coordination
+
+The compiled module also coordinates admitted local-brain turns through
+explicit RelayHost callbacks: scheduling, selected progress, an acknowledgment
+clock that starts before queueing, and deferred completion. Hosts supply the
+native brain and retain correlation, phrase and delivery policy. See the
+[relay runtime contract](docs/specs/relay-module-runtime.md).
+
+### Live sessions
+
+The compiled module owns the live provider loop through TinyAgentsLive and a
+bounded client/provider coordinator. Hosts reserve a lease, bind mechanical
+socket callbacks with `LiveBindTransport`, and supply prepared connection
+material and explicit declarations through `LiveStart`. The module handles
+polling, ordered effects, replay and cleanup; callbacks retain product policy
+and persistence. A declaration never grants execution permission.
+
+The minimal contract also supports manual `LiveSend`/`LiveRead` for hosts that
+need a custom transport, with replay until acknowledgment. Those operations
+are excluded once a module transport is bound. See the
+[live runtime contract](docs/specs/live-module-runtime.md) for bounds and
+callback cancellation requirements.
+
 ## Layout
 
 ```text

crates/tinyvoice-bus/src/lib.rs

@@ -15,6 +15,7 @@ mod error;
 pub mod capture;
 pub mod hotkey;
 pub mod intent;
+pub mod live;
 pub mod names;
 pub mod provider;
 pub mod relay;

crates/tinyvoice-bus/src/live/mod.rs

@@ -0,0 +1,168 @@
+//! Portable live websocket control vocabulary.
+
+pub mod session;
+/// Mechanical client socket and persistence callbacks for module-owned pumping.
+pub mod transport;
+
+use serde::{Deserialize, Serialize};
+
+/// A client control frame; audio travels separately as PCM16 bytes.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ClientFrame {
+    /// First-frame connection request; identities remain opaque host metadata.
+    Start {
+        /// Optional host provider selection.
+        #[serde(default)]
+        provider: Option<String>,
+        /// Optional host transcript identity.
+        #[serde(default)]
+        thread_id: Option<String>,
+        /// Optional host approval-routing identity.
+        #[serde(default)]
+        client_id: Option<String>,
+        /// Mono PCM16 input rate, defaulting to sixteen kHz.
+        #[serde(default = "default_input_rate")]
+        input_sample_rate: u32,
+    },
+    /// Typed user input.
+    Text {
+        /// Original user text.
+        text: String,
+    },
+    /// Interrupt the current provider reply.
+    Interrupt,
+    /// Ask the provider to close.
+    Stop,
+}
+
+fn default_input_rate() -> u32 {
+    16_000
+}
+
+/// Transport facts supplied to the module's control parser.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum TransportFrame {
+    /// UTF-8 JSON control input.
+    Text {
+        /// The original websocket text.
+        text: String,
+    },
+    /// Mono PCM16 little-endian input.
+    Audio {
+        /// PCM16 bytes.
+        pcm16: Vec<u8>,
+    },
+    /// The client disconnected.
+    Closed,
+    /// Ping, pong and other non-command frames.
+    Other,
+}
+
+/// Parse one control frame under the current session phase.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PrepareLiveInputRequest {
+    /// Whether the connection still requires its first start frame.
+    pub awaiting_start: bool,
+    /// Original transport frame.
+    pub frame: TransportFrame,
+}
+
+/// A parsed command; malformed later frames are deliberately ignored.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PreparedLiveInput {
+    /// An accepted control command.
+    Control(ClientFrame),
+    /// A non-control transport action.
+    Transport(LiveTransportAction),
+}
+
+/// A transport action requiring no JSON control parsing.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum LiveTransportAction {
+    /// Forward input audio.
+    Audio {
+        /// Original PCM16 bytes.
+        pcm16: Vec<u8>,
+    },
+    /// Close the provider sender.
+    Closed,
+    /// No provider action.
+    Ignore,
+}
+
+/// Who a final transcript belongs to.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TranscriptRole {
+    /// Spoken or typed user input.
+    User,
+    /// Spoken assistant output.
+    Agent,
+}
+
+/// A live server JSON frame; audio remains a separate binary transport action.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ServerFrame {
+    /// The provider connected.
+    Ready {
+        /// Provider session identity or the host fallback.
+        session_id: Option<String>,
+        /// Host-selected provider identifier.
+        provider: String,
+        /// Mono PCM16 output sample rate.
+        output_sample_rate: u32,
+        /// Opaque host transcript identity.
+        thread_id: Option<String>,
+    },
+    /// Partial or final speech transcript.
+    Transcript {
+        /// User or agent speech.
+        role: TranscriptRole,
+        /// Original transcript text.
+        text: String,
+        /// Whether this completes the utterance.
+        #[serde(rename = "final")]
+        is_final: bool,
+    },
+    /// A provider tool call entered the harness.
+    ToolStarted {
+        /// Provider call identity.
+        call_id: String,
+        /// Declared tool name.
+        name: String,
+    },
+    /// A tool call completed or was cancelled.
+    ToolFinished {
+        /// Provider call identity.
+        call_id: String,
+        /// Declared tool name.
+        name: String,
+        /// Whether the result was successful.
+        ok: bool,
+        /// Whether the provider cancelled the result.
+        cancelled: bool,
+    },
+    /// Provider playback was interrupted.
+    Interrupted,
+    /// The provider completed its turn.
+    TurnComplete,
+    /// A provider or connection error.
+    Error {
+        /// Stable portable error classification.
+        code: String,
+        /// Provider diagnostic.
+        message: String,
+        /// Whether the provider is terminating.
+        fatal: bool,
+    },
+    /// The provider connection ended.
+    Closed {
+        /// Established close diagnostic.
+        reason: String,
+    },
+}