whisper-nvidia-cli 0.1.0

One-shot agent-native local NVIDIA GPU speech-to-text CLI powered by whisper.cpp
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
//! Cooperative shutdown: first signal asks, second signal forces.
//!
//! Broken pipe stays the kernel default so stdout write becomes exit 141.
//!
//! Delivery is counted, never timed. A wall-clock window cannot tell one
//! deliberate second interrupt from two fast keystrokes, so the first
//! delivery always asks and the second always forces.

use std::path::{Path, PathBuf};
use std::process::Child;
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicU8, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};

static SHUTDOWN: AtomicBool = AtomicBool::new(false);
static SIGNAL: AtomicU8 = AtomicU8::new(0);
static TEMPS: Mutex<Vec<PathBuf>> = Mutex::new(Vec::new());
/// Live helper processes this invocation owns.
static CHILDREN: Mutex<Vec<(u64, Arc<Mutex<Child>>)>> = Mutex::new(Vec::new());
static NEXT_CHILD_ID: AtomicU64 = AtomicU64::new(0);
/// Serializes the two threads that can force an exit.
///
/// The deadline watchdog and the signal thread both clean up and then call
/// `process::exit`. Without this, the loser of the race exits while the winner
/// is still inside `remove_dir_all`, killing the cleanup it was performing.
/// The loser blocks here forever, which is correct: the winner is leaving.
static EXIT_LOCK: Mutex<()> = Mutex::new(());

/// Take a lock even if a previous holder panicked.
///
/// Cleanup that skips itself because some unrelated thread panicked leaves
/// files on disk, which is the one outcome this module exists to prevent.
fn lock_through_poison<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
    m.lock().unwrap_or_else(|e| e.into_inner())
}

/// Exit status of a forced interrupt, taken from the error that means it.
///
/// These three numbers used to be spelled out here as literals, while
/// `Error::exit_code` spelled the same three out again. Two independent copies
/// of a contract cannot disagree loudly: changing one side would have left the
/// other reporting the old code, and the only symptom would be an agent reading
/// an exit number that no longer matched the envelope. The forced-exit path
/// bypasses the error boundary by design — it calls `process::exit` so a wedged
/// verb cannot swallow the signal — but it can still ASK the boundary what the
/// number is, which is what these do.
fn exit_interrupted() -> i32 {
    i32::from(crate::error::Error::Interrupted.exit_code())
}

/// Exit status of a forced termination.
fn exit_terminated() -> i32 {
    i32::from(crate::error::Error::Terminated.exit_code())
}

/// Exit status of a blown deadline.
fn exit_timeout() -> i32 {
    i32::from(crate::error::Error::Timeout.exit_code())
}

/// Why the process is leaving.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShutdownReason {
    /// Nothing asked the process to stop.
    None,
    /// SIGINT asked for a graceful stop.
    Sigint,
    /// SIGTERM asked for a graceful stop.
    Sigterm,
    /// A repeated signal escalated the stop to immediate.
    Forced,
}

/// Keep SIGPIPE ignored so a closed consumer becomes a write error, not a kill.
///
/// This function used to install `SIG_DFL`, and the comment claimed that was
/// "the documented way to let a closed stdout become a write error the process
/// maps to exit 141". It is the opposite: the default disposition of SIGPIPE is
/// to TERMINATE, so the kernel killed this process at the first write to a
/// closed pipe. The 141 an observer saw came from the shell reporting the
/// signal, never from this binary deciding anything.
///
/// The cost was the whole point of this module. A killed process runs no
/// destructor, so the work directory registered in [`register_temp`] survived,
/// and any helper still running was never reaped — exactly the residue FR-039
/// forbids and FR-046 calls out with "não deixa lixo".
///
/// The Rust runtime already sets SIGPIPE to `SIG_IGN` before `main`, which
/// makes the write return `EPIPE`. That error travels the normal failure path,
/// becomes [`crate::error::Error::BrokenPipe`], and still exits 141 — the same
/// code FR-046 fixes, now reached by unwinding through the cleanup instead of
/// dying under it.
pub fn reset_sigpipe() {
    // Deliberately empty: the runtime default is the behaviour we want, and the
    // function stays so the call site keeps documenting the decision.
}

/// Install SIGINT and SIGTERM handling.
///
/// On Unix a dedicated thread consumes the signal stream, which counts
/// deliveries without `unsafe` and distinguishes SIGINT from SIGTERM.
pub fn install_handlers() {
    #[cfg(unix)]
    {
        use signal_hook::consts::{SIGINT, SIGTERM};
        use signal_hook::iterator::Signals;

        let Ok(mut signals) = Signals::new([SIGINT, SIGTERM]) else {
            return;
        };
        std::thread::spawn(move || {
            for sig in signals.forever() {
                // Publish the reason BEFORE the flag. Consumers read the flag
                // first and then ask for the reason, so the reverse order
                // leaves a window where a shutdown is visible but cannot be
                // classified, and the error gets dropped. Only this thread
                // writes these, so load-then-store races with nobody.
                if SHUTDOWN.load(Ordering::SeqCst) {
                    SIGNAL.store(3, Ordering::SeqCst);
                    force_exit(sig == SIGTERM);
                }
                SIGNAL.store(if sig == SIGTERM { 2 } else { 1 }, Ordering::SeqCst);
                SHUTDOWN.store(true, Ordering::SeqCst);
            }
        });
    }
    #[cfg(not(unix))]
    {
        let _ = ctrlc::set_handler(|| {
            // Same publication order as the Unix path: reason before flag.
            // Consumers read the flag first, so the reverse order leaves a
            // window where the shutdown is visible but unclassifiable.
            if SHUTDOWN.load(Ordering::SeqCst) {
                SIGNAL.store(3, Ordering::SeqCst);
                force_exit(false);
            }
            SIGNAL.store(1, Ordering::SeqCst);
            SHUTDOWN.store(true, Ordering::SeqCst);
        });
    }
}

/// Leave now, but never leave a temporary file or a helper process behind.
fn force_exit(terminated: bool) -> ! {
    // Held until `process::exit`. A second forcing thread parks here instead of
    // exiting on top of a cleanup that is still running.
    let _exit = lock_through_poison(&EXIT_LOCK);
    // Helpers die first: one of them may still be writing into a work dir.
    kill_children();
    cleanup_temps();
    std::process::exit(if terminated {
        exit_terminated()
    } else {
        exit_interrupted()
    });
}

/// Arm a whole-invocation deadline.
///
/// The engine abort callback only covers inference. A blocking read on stdin,
/// or a stalled download, would otherwise outlive `--timeout` entirely, so the
/// deadline has to be owned by the process rather than by one stage of it.
/// `target` is owned because the thread outlives the caller's frame. A deadline
/// that fires on a named target is the failure that most needs attribution: the
/// exit code alone does not say which file ran out of time.
pub fn arm_deadline(seconds: u64, correlation_id: &str, target: Option<(String, &'static str)>) {
    if seconds == 0 {
        return;
    }
    let correlation_id = correlation_id.to_string();
    std::thread::spawn(move || {
        std::thread::sleep(std::time::Duration::from_secs(seconds));
        let _exit = lock_through_poison(&EXIT_LOCK);
        let err = crate::error::Error::Timeout;
        // Report before leaving: a mute exit code makes the agent guess.
        let designated = target
            .as_ref()
            .map(|(resolved, source)| crate::error::TargetRef { resolved, source });
        let _ = crate::output::write_error(
            &err,
            &correlation_id,
            &crate::surface::Surface::default(),
            designated,
        );
        // A helper that ignores the clock would otherwise outlive the process
        // that spawned it, which breaks the one-shot contract outright.
        kill_children();
        cleanup_temps();
        std::process::exit(exit_timeout());
    });
}

/// Track a temporary path so a forced exit still removes it.
///
/// A forced exit skips destructors, so `tempfile` guards alone would leak.
pub fn register_temp(path: &Path) {
    lock_through_poison(&TEMPS).push(path.to_path_buf());
}

/// Stop tracking a temporary path that was already released normally.
pub fn release_temp(path: &Path) {
    lock_through_poison(&TEMPS).retain(|p| p != path);
}

/// Remove every tracked temporary path. Safe to call more than once.
///
/// The list stays locked for the whole removal. A concurrent caller therefore
/// waits for the removal to finish instead of seeing an emptied list and
/// concluding there was nothing to clean.
pub fn cleanup_temps() {
    let mut guard = lock_through_poison(&TEMPS);
    for path in guard.drain(..) {
        if path.is_dir() {
            let _ = std::fs::remove_dir_all(&path);
        } else {
            let _ = std::fs::remove_file(&path);
        }
    }
}

/// Spawn a child this process owns, in its own group, already tracked.
///
/// The single place a child is created. `nvidia-smi` used to be spawned by a
/// bare `Command::output()` elsewhere: not in a group, not tracked, and not
/// interruptible. Measured with a probe that hangs — a real failure mode on a
/// wedged driver — the first interrupt did nothing, the second forced 130, and
/// the probe's own child outlived the run because `kill_children` had never
/// heard of it.
///
/// The helper had already been given a group and a registration. Doing it in
/// one function rather than twice is what stops the third caller from being
/// born without either, which is how the second one happened.
///
/// Returns the tracking id and the shared handle; the caller must
/// [`release_child`] once it has reaped the process itself.
///
/// The process group is a Unix construct, so on Windows the child is spawned
/// without one and [`kill_child_tree`] can only reach the child itself. The
/// Windows equivalent is a Job Object, which this build does not create, so the
/// "no orphaned grandchild" guarantee is a Unix guarantee and not a universal
/// one. `doctor` publishes the difference under `child_tree_signal` rather than
/// leaving the caller to infer it from the platform.
pub fn spawn_tracked(cmd: &mut std::process::Command) -> std::io::Result<(u64, Arc<Mutex<Child>>)> {
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        // The group is what lets a forced exit reach the child's descendants.
        cmd.process_group(0);
    }
    let child = cmd.spawn()?;
    let child = Arc::new(Mutex::new(child));
    let id = register_child(Arc::clone(&child));
    Ok((id, child))
}

/// Track a helper process so a forced exit kills and reaps it.
///
/// A one-shot process that leaves a live child behind is not one-shot. The
/// handle is shared because the owner polls it while this module may have to
/// kill it from another thread.
pub fn register_child(child: Arc<Mutex<Child>>) -> u64 {
    let id = NEXT_CHILD_ID.fetch_add(1, Ordering::SeqCst);
    lock_through_poison(&CHILDREN).push((id, child));
    id
}

/// Stop tracking a helper that already exited on its own.
pub fn release_child(id: u64) {
    lock_through_poison(&CHILDREN).retain(|(known, _)| *known != id);
}

/// Kill and reap every tracked helper. Safe to call more than once.
///
/// Reaping matters as much as killing: a signalled child that is never waited
/// on becomes a zombie for as long as this process lives.
///
/// The group is signalled before the child, because a helper that spawns its
/// own worker hands that worker to init the moment the helper dies. Measured on
/// all three forced exits — 130, 143 and 124 — the helper was gone, the work
/// directory was removed, and the grandchild kept running under a new parent.
/// `Child::kill` names one pid and cannot reach below it; the helper is spawned
/// as its own group leader so that the negative pid names exactly its
/// descendants and nothing else on the host.
pub fn kill_children() {
    let taken: Vec<_> = lock_through_poison(&CHILDREN).drain(..).collect();
    for (_, child) in taken {
        let mut guard = lock_through_poison(&child);
        kill_child_tree(&mut guard);
    }
}

/// Kill a helper together with everything it spawned, then reap it.
///
/// This exists as one function because there are two places that stop a helper
/// and they must stop it the same way. The forced-exit path is the obvious one;
/// the cooperative poll loop is the one that actually runs most of the time,
/// and killing by pid in either place leaves the descendants behind.
///
/// The helper is spawned as its own process group leader, so the negative pid
/// names exactly its own descendants. Without that, this signal would reach the
/// caller's own group — every sibling in the operator's terminal included.
pub fn kill_child_tree(child: &mut Child) {
    #[cfg(unix)]
    {
        // The child has not been reaped yet, so its pid — and therefore its
        // group id — cannot have been reused by the kernel.
        let pgid = child.id() as libc::pid_t;
        // SAFETY: `kill` with a negative pid signals a process group. The group
        // was created by `process_group(0)` at spawn and holds this helper and
        // its descendants only.
        unsafe {
            libc::kill(-pgid, libc::SIGKILL);
        }
    }
    let _ = child.kill();
    let _ = child.wait();
}

/// True after the first interrupt.
/// The cooperative deadline, as milliseconds since the process armed it.
///
/// Zero means no deadline. Stored here rather than threaded through the decode
/// stack because the deadline belongs to the invocation, not to any one stage,
/// and five signatures would have to carry it to reach the packet loop.
static DEADLINE_MS: AtomicU64 = AtomicU64::new(0);
static START: Mutex<Option<std::time::Instant>> = Mutex::new(None);

/// Publish the deadline every stage can consult.
///
/// This is the cooperative instant, without the watchdog's grace: stages stop
/// on the deadline the caller asked for, and the watchdog exists only for the
/// stages that cannot stop themselves.
pub fn publish_deadline(seconds: u64) {
    if seconds == 0 {
        return;
    }
    *lock_through_poison(&START) = Some(std::time::Instant::now());
    DEADLINE_MS.store(seconds.saturating_mul(1000), Ordering::SeqCst);
}

/// True once the invocation is past its deadline.
///
/// Cheap enough to call inside a decode loop: one atomic load, and the clock is
/// only read when a deadline exists.
pub fn deadline_exceeded() -> bool {
    let ms = DEADLINE_MS.load(Ordering::SeqCst);
    if ms == 0 {
        return false;
    }
    let Some(start) = *lock_through_poison(&START) else {
        return false;
    };
    start.elapsed().as_millis() as u64 >= ms
}

/// True once a signal has asked the process to stop.
pub fn is_shutdown_requested() -> bool {
    SHUTDOWN.load(Ordering::SeqCst)
}

/// Classified interrupt reason.
pub fn shutdown_reason() -> ShutdownReason {
    match SIGNAL.load(Ordering::SeqCst) {
        1 => ShutdownReason::Sigint,
        2 => ShutdownReason::Sigterm,
        3 => ShutdownReason::Forced,
        _ => ShutdownReason::None,
    }
}

/// Map a shutdown into a contract error.
pub fn shutdown_error() -> Option<crate::error::Error> {
    match shutdown_reason() {
        ShutdownReason::Forced | ShutdownReason::Sigterm => Some(crate::error::Error::Terminated),
        ShutdownReason::Sigint => Some(crate::error::Error::Interrupted),
        ShutdownReason::None => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn tracked_temp_is_removed() {
        let dir = tempfile::tempdir().expect("tempdir");
        let file = dir.path().join("leftover");
        std::fs::write(&file, b"x").expect("write");
        register_temp(&file);
        cleanup_temps();
        assert!(!file.exists());
    }

    #[test]
    fn released_temp_is_not_tracked() {
        let dir = tempfile::tempdir().expect("tempdir");
        let file = dir.path().join("kept");
        std::fs::write(&file, b"x").expect("write");
        register_temp(&file);
        release_temp(&file);
        cleanup_temps();
        assert!(file.exists());
    }

    #[test]
    fn sigterm_maps_to_terminated() {
        SIGNAL.store(2, Ordering::SeqCst);
        assert_eq!(shutdown_reason(), ShutdownReason::Sigterm);
        assert!(matches!(
            shutdown_error(),
            Some(crate::error::Error::Terminated)
        ));
        SIGNAL.store(0, Ordering::SeqCst);
    }
}