Own live provider and socket coordination in the compiled module

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

@@ -0,0 +1,22 @@
+#!/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"
+prefix="$(pwd -P)/crates/tinyvoice-module/src/service/live/"
+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 6 ]]; then
+  echo "expected six covered live-runtime source files, 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 'Live runtime files below %s%% line coverage:\n%s\n' "$minimum" "$failures" >&2
+  exit 1
+fi

.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
           # This job executes repository code (cargo build/test); don't persist
           # the token in git config.
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - name: Install X11 development libraries
         run: sudo apt-get update && sudo apt-get install --yes libx11-dev libxtst-dev
@@ -72,15 +72,25 @@ jobs:
       - name: Test default features
         run: cargo test
 
+      - name: Verify compiled live module boundary
+        run: |
+          cargo build --locked --manifest-path crates/tinyvoice-module/Cargo.toml --lib
+          cargo run --locked --manifest-path crates/tinyvoice-module/Cargo.toml --example verify_module -- crates/tinyvoice-module/target/debug/libtinyvoice_module.so
+
       - name: Require 90% line coverage in every source file
         run: .github/scripts/check-file-coverage.sh 90 coverage.json
 
+      - name: Require 90% live module file coverage
+        run: .github/scripts/check-live-module-coverage.sh 90 live-module-coverage.json
+
       - name: Upload coverage report
         if: ${{ always() }}
         uses: actions/upload-artifact@v7
         with:
           name: coverage-json
-          path: coverage.json
+          path: |
+            coverage.json
+            live-module-coverage.json
           if-no-files-found: ignore
 
   windows-hotkeys:
@@ -90,7 +100,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - uses: dtolnay/rust-toolchain@stable
 
@@ -112,7 +122,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - name: Install X11 development libraries
         run: sudo apt-get update && sudo apt-get install --yes libx11-dev libxtst-dev
@@ -136,7 +146,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - name: Install X11 development libraries
         run: sudo apt-get update && sudo apt-get install --yes libx11-dev libxtst-dev
@@ -169,7 +179,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - name: Check advisories, licenses, bans, and sources
         uses: EmbarkStudios/cargo-deny-action@v2

.github/workflows/release.yml

@@ -35,7 +35,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-          submodules: true
+          submodules: recursive
 
       - name: Install ALSA development files
         run: sudo apt-get update && sudo apt-get install --yes libasound2-dev
@@ -280,7 +280,7 @@ jobs:
         with:
           ref: ${{ needs.publish.outputs.tag }}
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - uses: dtolnay/rust-toolchain@stable
 
@@ -397,7 +397,7 @@ jobs:
         with:
           ref: ${{ needs.publish.outputs.tag }}
           persist-credentials: false
-          submodules: true
+          submodules: recursive
 
       - name: Download workflow artifacts
         uses: actions/download-artifact@v8

.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 42 methods under contract 1.7.
 
 ## Methods
 
@@ -21,6 +21,14 @@ 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 |
+| `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 |

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,21 @@ 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.
 
+### 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

@@ -13,6 +13,7 @@
 pub mod capture;
 pub mod hotkey;
 pub mod intent;
+pub mod live;
 pub mod names;
 pub mod relay;
 pub mod transcript;

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,
+    },
+}