agent.libx.js 0.92.5 → 0.92.7

package/dist/index.d.ts

@@ -745,6 +745,11 @@ interface AudioSink {
     playedMs(): number;
     /** stop playback NOW (barge-in primitive) */
     kill(): void;
+    /** optional exact-sample pause/resume — enables the overlap trail-off tier (web: AudioContext
+     *  suspend/resume; CLI AEC helper: control frames). Sinks without it degrade to interrupt-only
+     *  turn-taking. Nothing is lost across a pause; playedMs/drainMs must exclude paused time. */
+    pause?(): void;
+    resume?(): void;
 }
 /** Static key (server/CLI) or an async getter (browser: fetch a short-lived token from YOUR
  *  backend). Getters are invoked on EVERY (re)connect — temp tokens expire, so a reconnect
@@ -794,6 +799,18 @@ declare class VoiceEngineOptions {
     /** heuristic (non-AEC) energy barge-in tuning */
     bargeRmsMult: number;
     bargeRmsFloor: number;
+    /** Overlap turn-taking (AEC tier, needs player.pause/resume) — human phone-call model:
+     *  onset → PAUSE (exact-sample hold, nothing lost); sustained overlap → cede (interrupt; the LLM
+     *  re-enters). Brief overlaps that die out (backchannels — "mm-hm", decided by DURATION, not
+     *  vocabulary) resume from the precise sample and are dropped. false disables. */
+    overlapPause: boolean;
+    /** sustained overlap ≥ this → cede the turn */
+    overlapSustainMs: number;
+    /** quiet for this long while paused → resume, drop the interjection */
+    overlapResumeMs: number;
+    /** energy floor for "overlap candidate" — must sit ABOVE typical room ambient (~110 rms measured;
+     *  ungated ambient re-arming the resume timer forever was a live wedge). User speech ≫ 300. */
+    overlapRms: number;
 }
 declare class VoiceEngine {
     options: VoiceEngineOptions;
@@ -817,6 +834,10 @@ declare class VoiceEngine {
     private pendingUtt;
     private pendingTimer;
     private lastInterrupted;
+    private pausedAt;
+    private overlapLoud;
+    private overlapLastLoudAt;
+    private resumeTimer;
     constructor(options?: Partial<VoiceEngineOptions>);
     start(): Promise<void>;
     get usingAec(): boolean;
@@ -843,9 +864,22 @@ declare class VoiceEngine {
     private words;
     private novelWords;
     private echoActive;
+    /** Genuine user speech vs our own bleed (AEC tier): novel words must DOMINATE, not merely exist.
+     *  Degraded AEC + an STT mis-hearing manufactures a single novel word out of pure echo (a name or
+     *  rare word in our own reply comes back transcribed slightly differently — 1 novel / N words).
+     *  A real interjection is mostly novel ("stop", "wait what") — short utterances pass on ratio,
+     *  longer ones on count. */
+    private genuine;
     private handlePartial;
     private handleUtterance;
     private flushUtterance;
+    private get overlapCapable();
+    /** Overlap turn-taking (AEC tier): onset → pause (exact-sample hold); sustained → cede; died out
+     *  → resume. No vocabulary anywhere — duration and persistence decide (backchannels are short
+     *  and stop). Nothing is lost across a pause, so a false positive costs only a brief hold. */
+    private handleOverlap;
+    private armResume;
+    private resetOverlap;
     /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
     private handleLevel;
 }

package/dist/index.js

@@ -3652,12 +3652,14 @@ ${recent}` : brief;
         report.output(chunk);
       }
     } : base;
+    const workerHost = o.host?.ask ? { ask: (q) => o.host.ask(q) } : void 0;
     const worker = new Agent({
       ai: o.ai,
       fs: o.fs,
       model: o.workerModel,
       ...o.workerOptions,
       // may override ai/fs/model/tools/… —
+      ...workerHost ? { host: workerHost } : {},
       ...hooks ? { hooks } : {},
       signal: controller.signal
       // …but never the per-task cancellation signal
@@ -4000,6 +4002,18 @@ var VoiceEngineOptions = class {
   /** heuristic (non-AEC) energy barge-in tuning */
   bargeRmsMult = 2;
   bargeRmsFloor = 500;
+  /** Overlap turn-taking (AEC tier, needs player.pause/resume) — human phone-call model:
+   *  onset → PAUSE (exact-sample hold, nothing lost); sustained overlap → cede (interrupt; the LLM
+   *  re-enters). Brief overlaps that die out (backchannels — "mm-hm", decided by DURATION, not
+   *  vocabulary) resume from the precise sample and are dropped. false disables. */
+  overlapPause = true;
+  /** sustained overlap ≥ this → cede the turn */
+  overlapSustainMs = 350;
+  /** quiet for this long while paused → resume, drop the interjection */
+  overlapResumeMs = 700;
+  /** energy floor for "overlap candidate" — must sit ABOVE typical room ambient (~110 rms measured;
+   *  ungated ambient re-arming the resume timer forever was a live wedge). User speech ≫ 300. */
+  overlapRms = 300;
 };
 var VoiceEngine = class {
   options;
@@ -4030,6 +4044,13 @@ var VoiceEngine = class {
   // endpointed text held for the merge window
   pendingTimer = null;
   lastInterrupted = null;
+  // overlap (pause) tier state — AEC + pause-capable sinks only
+  pausedAt = 0;
+  overlapLoud = 0;
+  // loud chunks since pause (sustain must be real sound, not two clicks)
+  overlapLastLoudAt = 0;
+  // continuity guard: a gap re-arms the onset (sparse noise ≠ sustained speech)
+  resumeTimer = null;
   constructor(options) {
     this.options = { ...new VoiceEngineOptions(), ...options };
     const o = this.options;
@@ -4077,6 +4098,7 @@ var VoiceEngine = class {
       this.drainTimer = null;
     }
     this.interrupted = false;
+    this.resetOverlap(true);
     if (!this.speaking) this.player.markTurn();
     this.speaking = true;
     this.ctxOpen = true;
@@ -4111,6 +4133,10 @@ var VoiceEngine = class {
         this.drainTimer = null;
         return;
       }
+      if (this.pausedAt) {
+        this.drainTimer = setTimeout(settle, 250);
+        return;
+      }
       this.drainTimer = null;
       this.speaking = false;
       this.echoUntil = now() + 2500;
@@ -4142,6 +4168,7 @@ var VoiceEngine = class {
       clearTimeout(this.drainTimer);
       this.drainTimer = null;
     }
+    this.resetOverlap(false);
     const heardChars = Math.round(Math.max(0, this.player.playedMs()) / 1e3 * 15);
     if (this.reply) this.lastInterrupted = { full: this.reply, heard: this.reply.slice(0, heardChars) };
     this.speaking = false;
@@ -4156,6 +4183,7 @@ var VoiceEngine = class {
     this.setState("listening");
   }
   stop() {
+    if (this.resumeTimer) clearTimeout(this.resumeTimer);
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
     if (this.drainTimer) clearTimeout(this.drainTimer);
     this.stt.stop();
@@ -4173,9 +4201,19 @@ var VoiceEngine = class {
   echoActive() {
     return this.speaking || now() < this.echoUntil;
   }
+  /** Genuine user speech vs our own bleed (AEC tier): novel words must DOMINATE, not merely exist.
+   *  Degraded AEC + an STT mis-hearing manufactures a single novel word out of pure echo (a name or
+   *  rare word in our own reply comes back transcribed slightly differently — 1 novel / N words).
+   *  A real interjection is mostly novel ("stop", "wait what") — short utterances pass on ratio,
+   *  longer ones on count. */
+  genuine(text) {
+    const total = this.words(text).length;
+    const novel = this.novelWords(text).length;
+    return novel > 0 && novel / Math.max(1, total) > 0.5;
+  }
   handlePartial(text) {
     if (this.speaking) {
-      const barge = this.novelWords(text).length >= (this.usingAec ? 1 : this.suspectUntil ? 1 : 2);
+      const barge = this.overlapCapable ? false : this.usingAec ? this.genuine(text) : this.novelWords(text).length >= (this.suspectUntil ? 1 : 2);
       if (barge) {
         const phase = this.ctxOpen ? "speaking" : "drain";
         this.interrupt();
@@ -4189,10 +4227,14 @@ var VoiceEngine = class {
         this.pendingTimer = null;
       }
     }
-    if (!this.echoActive() || this.novelWords(text).length >= 1) this.options.onPartial(text);
+    if (!this.echoActive() || (this.usingAec ? this.genuine(text) : this.novelWords(text).length >= 1)) this.options.onPartial(text);
   }
   handleUtterance(text) {
-    if (this.echoActive() && this.novelWords(text).length < (this.usingAec ? 1 : 2)) {
+    if (this.speaking && this.ctxOpen && this.overlapCapable) {
+      this.stt.reset();
+      return;
+    }
+    if (this.echoActive() && (this.usingAec ? !this.genuine(text) : this.novelWords(text).length < 2)) {
       this.stt.reset();
       return;
     }
@@ -4215,9 +4257,62 @@ var VoiceEngine = class {
     this.pendingUtt = "";
     if (text) this.options.onUtterance(text);
   }
+  get overlapCapable() {
+    return this.usingAec && this.options.overlapPause && !!this.player.pause && !!this.player.resume;
+  }
+  /** Overlap turn-taking (AEC tier): onset → pause (exact-sample hold); sustained → cede; died out
+   *  → resume. No vocabulary anywhere — duration and persistence decide (backchannels are short
+   *  and stop). Nothing is lost across a pause, so a false positive costs only a brief hold. */
+  handleOverlap(rms) {
+    const o = this.options;
+    if (!this.speaking || !this.overlapCapable) return;
+    if (rms < o.overlapRms) return;
+    const t = now();
+    if (!this.pausedAt) {
+      this.pausedAt = t;
+      this.overlapLoud = 1;
+      this.overlapLastLoudAt = t;
+      this.player.pause();
+      this.armResume();
+      return;
+    }
+    if (t - this.overlapLastLoudAt > 300) {
+      this.pausedAt = t;
+      this.overlapLoud = 1;
+      this.overlapLastLoudAt = t;
+      this.armResume();
+      return;
+    }
+    this.overlapLastLoudAt = t;
+    this.overlapLoud++;
+    if (t - this.pausedAt >= o.overlapSustainMs && this.overlapLoud >= 4) {
+      const phase = this.ctxOpen ? "speaking" : "drain";
+      this.interrupt();
+      this.options.onBargeIn(phase);
+      return;
+    }
+    this.armResume();
+  }
+  armResume() {
+    if (this.resumeTimer) clearTimeout(this.resumeTimer);
+    this.resumeTimer = setTimeout(() => {
+      this.resumeTimer = null;
+      if (!this.pausedAt) return;
+      this.resetOverlap(true);
+    }, this.options.overlapResumeMs);
+  }
+  resetOverlap(resume) {
+    if (this.resumeTimer) {
+      clearTimeout(this.resumeTimer);
+      this.resumeTimer = null;
+    }
+    if (this.pausedAt && resume) this.player.resume?.();
+    this.pausedAt = 0;
+    this.overlapLoud = 0;
+  }
   /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
   handleLevel(rms) {
-    if (this.usingAec) return;
+    if (this.usingAec) return this.handleOverlap(rms);
     if (!this.speaking) {
       this.baseline = 0;
       this.hot = 0;