@livx.cc/agentx 0.99.118 → 0.99.119

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentOptions, H as Hooks, p as RunResult, f as Decider, A as Agent, i as PermissionPolicy, G as Gender, L as LineKind, C as ChannelMode, q as SecondChannelOptions, S as SecondChannel } from './secondChannel-BCEr_QyM.js';
-export { b as ChatFragment, c as Classification, d as Classifier, e as CompactResult, D as DEFAULT_MUTATING, g as Decision, M as ModelRouter, h as ModelRouterOptions, P as PermissionOptions, j as PermissionRule, k as PreToolUseDecision, R as ReasoningEffort, l as RecordingHooks, m as RecordingLifecycle, n as RouteDecision, o as RouterState, T as Tier, r as ToolUse, s as ToolUseMeta, t as claudeCodeDisallowedTools, u as composeHooks, v as estimateTokens, w as jevAvailable, x as jevClassifier, y as pickTier, z as planMode, B as reasoningToChatFragment } from './secondChannel-BCEr_QyM.js';
+import { a as AgentOptions, H as Hooks, p as RunResult, f as Decider, A as Agent, i as PermissionPolicy, G as Gender, L as LineKind, C as ChannelMode, q as SecondChannelOptions, S as SecondChannel } from './secondChannel-DepBV0Zv.js';
+export { b as ChatFragment, c as Classification, d as Classifier, e as CompactResult, D as DEFAULT_MUTATING, g as Decision, M as ModelRouter, h as ModelRouterOptions, P as PermissionOptions, j as PermissionRule, k as PreToolUseDecision, R as ReasoningEffort, l as RecordingHooks, m as RecordingLifecycle, n as RouteDecision, o as RouterState, T as Tier, r as ToolUse, s as ToolUseMeta, t as claudeCodeDisallowedTools, u as composeHooks, v as estimateTokens, w as jevAvailable, x as jevClassifier, y as pickTier, z as planMode, B as reasoningToChatFragment } from './secondChannel-DepBV0Zv.js';
 export { MODEL_ALIASES, ModelSwitch, ResolveModelSwitchOpts, latestClaude, modelShortLabel, resolveModelAlias, resolveModelSwitch } from './models.js';
 import { IFilesystem, FileMetadata } from '@livx.cc/wcli/core';
 export { CommandExecutor, FileMetadata, IFilesystem, IndexedDbFilesystem, MemFilesystem, registerHeadlessCommands } from '@livx.cc/wcli/core';
@@ -1666,15 +1666,40 @@ interface MainEvent {
     name?: string;
     args?: unknown;
 }
+/** One turn's timeline, ms from the user's last word (the STT's word clock when the host passes it, else the final's
+ *  arrival). A stage that did not happen is absent. */
+interface TurnTimeline {
+    /** The STT's final reached the call (STT latency + silence endpoint + the engine's merge hold). */
+    final?: number;
+    /** TurnGate sent the turn to MAIN (its own hold for a mid-phrase line included). */
+    sent?: number;
+    /** The fill channel chose its first line for this turn (bridge/filler/progress) — handed to the host, not yet heard. */
+    fill?: number;
+    fillKind?: string;
+    /** That line's audio started (hostAudio: the host's player; else = fill). */
+    fillAudio?: number;
+    /** MAIN's first event (text or tool). */
+    mainFirst?: number;
+    /** MAIN's first text token. */
+    mainText?: number;
+    /** MAIN's first audio started (the host's player). */
+    mainAudio?: number;
+    /** false: the host gave no last-word time — the anchor is the final's arrival. */
+    lastWord: boolean;
+    /** How the turn ended: answered = MAIN audio played · cut = barged · replaced = a fuller re-final took it · silent = no MAIN audio. */
+    end?: 'answered' | 'cut' | 'replaced' | 'silent';
+}
 interface CallMetric {
-    name: 'first_sound' | 'first_word' | 'turn' | 'drop' | 'hold' | 'fill' | 'lang';
+    name: 'first_sound' | 'first_word' | 'turn' | 'drop' | 'hold' | 'fill' | 'lang' | 'timeline';
     id?: string;
-    /** ms from the user's final (the first final of a held/merged turn) */
+    /** ms from the user's last word (see TurnTimeline) */
     ms?: number;
     by?: 'fill' | 'progress' | 'main';
     kind?: string;
     text?: string;
     lang?: string | null;
+    /** name 'timeline': the turn's stages. */
+    timeline?: TurnTimeline;
 }
 declare class VoiceCallOptions {
     /** Host runs MAIN with exactly `text` (a replace: roll the `replaces` turn back first). */
@@ -1707,6 +1732,9 @@ declare class VoiceCallOptions {
     /** Extra SecondChannel options (tests, tuning). speak/show/cancel are always VoiceCall's own. */
     channel: Partial<SecondChannelOptions>;
     onMetric: (m: CallMetric) => void;
+    /** The host reports when a fill line's audio REALLY starts (heard()). Off: a line handed to `speak` counts as heard —
+     *  right only for a host whose speak() plays at once (a relay host would count lines its player later dropped). */
+    hostAudio: boolean;
     now: () => number;
     /** An aside (aside()) needs this long since the last one — a cue answered every time sounds scripted. */
     asideGapMs: number;
@@ -1722,6 +1750,8 @@ declare class VoiceCall {
     private lastAside;
     private lastAudibleAt;
     private firstFinalAt;
+    private lastWordAt;
+    private earlyHeard;
     private progressTimer;
     private ended;
     constructor(options?: Partial<VoiceCallOptions> | undefined);
@@ -1738,14 +1768,25 @@ declare class VoiceCall {
     setLanguage(tag: string): void;
     /** STT partial (the whole partial). */
     interim(text: string, _atMs?: number, aec?: boolean): void;
-    /** STT final → TurnGate. */
-    final(text: string, sttId?: string): void;
+    /** STT final → TurnGate. `lastWordAgoMs`: how long ago the user's last word of it ended (the STT's word clock,
+     *  bod-voice UtteranceMeta.lastWordAgoMs) — the turn's latency anchor; absent = the final's arrival. `lang`: the
+     *  language the STT identified for it (UtteranceMeta.language) — what the turn's words follow when they alone can't tell
+     *  (a short English line after a Hebrew one left the fill channel on Hebrew: its bridge was refused, the turn silent). */
+    final(text: string, sttId?: string, o?: {
+        lastWordAgoMs?: number;
+        lang?: string;
+    }): void;
+    private finalAt;
+    private sttLang;
+    /** The host's player started a line's audio now (or in `inMs`): `fill`/`progress` = the fill channel's, `main` = MAIN's
+     *  reply (as main({type:'audio'})). With hostAudio this is what first_sound counts. */
+    heard(by: 'fill' | 'progress' | 'main', inMs?: number): void;
     /** A v2 host that decides turns itself: the user's line already went to MAIN (no TurnGate, no sendTurn) — the fill
      *  channel follows its language and covers the wait. */
     hostTurn(text: string): void;
     pause(ms: number): void;
-    /** MAIN's stream. */
-    main(ev: MainEvent): void;
+    /** MAIN's stream. (`inMs`: an audio event's start is that far ahead — the host player's queue.) */
+    main(ev: MainEvent, inMs?: number): void;
     /** The user barged in (hard): cut fill + MAIN audio (the host cuts its own), abort a running MAIN turn. */
     barge(): void;
     /** Soft barge-in: keep (a listener cue — no turn) or cut (→ barge()). */
@@ -1768,6 +1809,9 @@ declare class VoiceCall {
     /** Every fill/progress line passes here: only in the turn's known language, never after the call ended. */
     private say;
     private sounded;
+    /** The turn is over (answered + audible, replaced, the next turn, the call's end): its timeline, once. A turn whose MAIN
+     *  never became audible still reports first_word — with no ms and why (cut / replaced / silent) — so every turn has one. */
+    private close;
     private onTool;
     private clearProgress;
 }

package/dist/index.js

@@ -13104,11 +13104,26 @@ var SecondChannel = class {
   }
   /** Hard gates every line passes, whoever proposed it. */
   allowed(k) {
-    if (!this.o.kinds.includes(k)) return false;
-    if (this.audioLocked || this.inflight || this.o.now() - this.lastAt < this.o.minGapMs || k === this.lastKind && (k !== "backchannel" || this.o.now() - this.lastAt < this.o.backchannelGapMs)) return false;
-    if (k === "backchannel") return this.o.aec && this.userSpeaking && this.main === "idle" && !this.capped();
-    if (k === "filler") return !this.userSpeaking && this.main === "idle";
-    return (this.main === "queued" || this.main === "thinking") && !this.bridged;
+    return !this.blocked(k);
+  }
+  /** Why a line of kind `k` can't play now ('' = it can) — the call's ledger names a missing bridge's cause. */
+  blocked(k) {
+    if (!this.o.kinds.includes(k)) return "kind off";
+    if (this.audioLocked) return `main audio (${this.main})`;
+    if (this.inflight) return "a line still playing";
+    if (this.o.now() - this.lastAt < this.o.minGapMs) return `${Math.round(this.o.now() - this.lastAt)}ms since the last line`;
+    if (k === this.lastKind && (k !== "backchannel" || this.o.now() - this.lastAt < this.o.backchannelGapMs)) return "same kind as the last line";
+    if (k === "backchannel") return this.o.aec && this.userSpeaking && this.main === "idle" && !this.capped() ? "" : "not a backchannel moment";
+    if (k === "filler") return !this.userSpeaking && this.main === "idle" ? "" : "not a filler moment";
+    return this.bridged ? "bridged already" : this.main === "queued" || this.main === "thinking" ? "" : `main ${this.main}`;
+  }
+  /** Why this turn gets no bridge by rule ('' = it may) — language, a quick/phatic turn, or blocked(). */
+  bridgeBlock() {
+    const w = words2(this.heard);
+    if (!this.lang) return "language unknown";
+    if (w.length <= 3 || w.length <= 6 && isPhatic(this.heard, this.bank)) return w.length <= 3 ? "quick turn" : "phatic";
+    if (w.length < this.o.bridgeMinWords) return `under ${this.o.bridgeMinWords} words`;
+    return this.blocked("bridge");
   }
   bcTimes = [];
   capped() {
@@ -13155,7 +13170,10 @@ var SecondChannel = class {
     return breath || /[,;:…]$/.test(this.heard);
   }
   async consider(trigger, pauseMs, breath = false, cue = null) {
-    if (this.busy) return;
+    if (this.busy) {
+      if (trigger === "working") this.o.onEvent({ trigger, rule: "silence", ms: 0, acted: "silence", reason: "deciding another line" });
+      return;
+    }
     const n0 = words2(this.heard).length;
     this.decidedAt = n0;
     if (!(this.o.anticipate && this.plan && trigger === "interim")) cue = null;
@@ -13165,7 +13183,10 @@ var SecondChannel = class {
       log28.info("chatty mode without echo cancellation \u2014 normal timing (our lines would re-trigger the mic)");
     }
     const rule = this.rule(trigger, pauseMs, breath, cue);
-    if (rule === "silence") return;
+    if (rule === "silence") {
+      if (trigger === "working") this.o.onEvent({ trigger, rule, ms: 0, acted: "silence", reason: this.bridgeBlock() || "rule" });
+      return;
+    }
     this.busy = true;
     const gen = this.gen, t0 = this.o.now();
     const ev = (e) => this.o.onEvent({ trigger, rule, ms: Math.round(this.o.now() - t0), ...cue ? { cue: cue.line } : {}, ...e });
@@ -13359,6 +13380,9 @@ var VoiceCallOptions = class {
   channel = {};
   onMetric = () => {
   };
+  /** The host reports when a fill line's audio REALLY starts (heard()). Off: a line handed to `speak` counts as heard —
+   *  right only for a host whose speak() plays at once (a relay host would count lines its player later dropped). */
+  hostAudio = false;
   now = () => performance.now();
   /** An aside (aside()) needs this long since the last one — a cue answered every time sounds scripted. */
   asideGapMs = 8e3;
@@ -13378,11 +13402,17 @@ var VoiceCall = class {
       } : {},
       mode: o.mode,
       aec: o.aec,
-      bridgeDelayMs: 700,
+      // v3 §3: first sound <1.2s p50 from the last word — the endpoint takes ~0.6s and the bridge's TTS ~0.2s, so the bridge
+      // goes 300ms after the turn if MAIN is still silent (it always is that early: warm MAIN's first token is ≥1s), no veto
+      bridgeDelayMs: 300,
       instantBridge: true,
-      // v3 §3: first sound <1.2s p50 — a bridge at 700ms if MAIN is still silent, no veto, no wait
       ...this.lang ? { lang: this.lang } : {},
       ...o.channel,
+      // the ledger: a turn's bridge moment that stayed silent, and why (its wait then has no first sound until MAIN speaks)
+      onEvent: (e) => {
+        if (e.trigger === "working" && e.acted !== "spoken") o.onMetric({ name: "drop", ...this.cur ? { id: this.cur.id } : {}, kind: `no bridge: ${e.reason ?? e.acted}`, ...e.text ? { text: e.text } : {} });
+        o.channel.onEvent?.(e);
+      },
       speak: (text, kind) => this.say(text, kind),
       show: (text, kind) => o.show(text, kind),
       cancel: () => o.cancel(),
@@ -13409,6 +13439,10 @@ var VoiceCall = class {
   lastAudibleAt = -Infinity;
   firstFinalAt = null;
   // the first final of the turn being formed (hold/merge)
+  lastWordAt = null;
+  // the user's last word before the turn being formed (its latest final's)
+  earlyHeard = null;
+  // a fill line heard while that turn was still held
   progressTimer = null;
   ended = false;
   get o() {
@@ -13437,12 +13471,37 @@ var VoiceCall = class {
     this.follow(text);
     this.fill.onInterim(text);
   }
-  /** STT final → TurnGate. */
-  final(text, sttId) {
+  /** STT final → TurnGate. `lastWordAgoMs`: how long ago the user's last word of it ended (the STT's word clock,
+   *  bod-voice UtteranceMeta.lastWordAgoMs) — the turn's latency anchor; absent = the final's arrival. `lang`: the
+   *  language the STT identified for it (UtteranceMeta.language) — what the turn's words follow when they alone can't tell
+   *  (a short English line after a Hebrew one left the fill channel on Hebrew: its bridge was refused, the turn silent). */
+  final(text, sttId, o = {}) {
     if (this.ended) return;
-    this.firstFinalAt ??= this.o.now();
+    const now3 = this.o.now(), { lastWordAgoMs } = o;
+    this.firstFinalAt ??= now3;
+    this.sttLang = o.lang ? primaryLang(o.lang) : null;
+    this.lastWordAt = typeof lastWordAgoMs === "number" && lastWordAgoMs >= 0 ? now3 - lastWordAgoMs : null;
+    this.finalAt = now3;
     this.gate.final(text, sttId);
   }
+  finalAt = 0;
+  sttLang = null;
+  // the STT's language for the final being followed
+  /** The host's player started a line's audio now (or in `inMs`): `fill`/`progress` = the fill channel's, `main` = MAIN's
+   *  reply (as main({type:'audio'})). With hostAudio this is what first_sound counts. */
+  heard(by, inMs = 0) {
+    if (this.ended) return;
+    if (by === "main") return this.main({ type: "audio", ...this.cur ? { id: this.cur.id } : {} }, inMs);
+    const at = this.o.now() + Math.max(0, inMs);
+    if (this.gate.holding || !this.cur || this.cur.closed) {
+      this.earlyHeard ??= { at, by };
+      return;
+    }
+    this.lastAudibleAt = at;
+    const c = this.cur;
+    c.marks.fillAudio ??= at;
+    this.sounded(c, by, at);
+  }
   /** A v2 host that decides turns itself: the user's line already went to MAIN (no TurnGate, no sendTurn) — the fill
    *  channel follows its language and covers the wait. */
   hostTurn(text) {
@@ -13453,8 +13512,8 @@ var VoiceCall = class {
   pause(ms) {
     if (!this.ended) this.fill.onPause(ms);
   }
-  /** MAIN's stream. */
-  main(ev) {
+  /** MAIN's stream. (`inMs`: an audio event's start is that far ahead — the host player's queue.) */
+  main(ev, inMs = 0) {
     const c = this.cur;
     if (!c || ev.id && ev.id !== c.id) return;
     switch (ev.type) {
@@ -13463,6 +13522,8 @@ var VoiceCall = class {
         return;
       case "text":
         if (!ev.text) return;
+        c.marks.mainFirst ??= this.o.now();
+        c.marks.mainText ??= this.o.now();
         if (!c.streamed) {
           c.streamed = true;
           this.gate.replyStarted(c.id);
@@ -13472,25 +13533,32 @@ var VoiceCall = class {
         this.fill.onMainTokens(ev.text);
         return;
       case "tool":
+        c.marks.mainFirst ??= this.o.now();
         this.gate.replyStarted(c.id);
         void this.onTool(c, ev.name ?? "", ev.args);
         return;
       case "tool_done":
         return;
-      case "audio":
-        this.lastAudibleAt = this.o.now();
+      case "audio": {
+        const at = this.o.now() + Math.max(0, inMs);
+        this.lastAudibleAt = at;
         this.fill.onAgentState("first_audio");
-        this.sounded(c, "main");
+        this.sounded(c, "main", at);
         if (!c.worded) {
           c.worded = true;
-          this.o.onMetric({ name: "first_word", id: c.id, ms: Math.round(this.o.now() - c.at), by: "main" });
+          c.marks.mainAudio = at;
+          this.o.onMetric({ name: "first_word", id: c.id, ms: Math.round(at - c.at), by: "main" });
         }
+        if (c.done) this.close(c, "answered");
         return;
+      }
       case "done":
       case "error":
         c.running = false;
+        c.done = true;
         this.clearProgress();
         this.fill.onAgentState("idle");
+        if (c.worded) this.close(c, "answered");
         return;
     }
   }
@@ -13507,6 +13575,7 @@ var VoiceCall = class {
       this.cur.running = false;
       this.o.abortTurn(this.cur.id);
     }
+    if (this.cur && !this.cur.worded) this.cur.end ??= "cut";
   }
   /** Soft barge-in: keep (a listener cue — no turn) or cut (→ barge()). */
   async overlap(text) {
@@ -13536,6 +13605,7 @@ var VoiceCall = class {
     return this.fill.drain();
   }
   end() {
+    if (this.cur) this.close(this.cur);
     this.ended = true;
     this.gate.end();
     this.clearProgress();
@@ -13544,24 +13614,39 @@ var VoiceCall = class {
   /** Follow the user's language from their own words: a confident detection, else the current language if the words
    *  fit it, else unknown (silent). Pinned into the channel so its own detection never diverges. */
   follow(text) {
-    const l = detectLanguage(text) ?? (this.lang && fitsLanguage(text, this.lang) ? this.lang : null);
+    const fits = (l2) => l2 && fitsLanguage(text, l2) ? l2 : null;
+    const l = detectLanguage(text) ?? fits(this.sttLang) ?? fits(this.lang);
     if (l !== this.lang) this.o.onMetric({ name: "lang", lang: l, text });
     this.lang = l;
     if (l) this.fill.setLanguage(l, true);
   }
   onTurn(t) {
-    const at = this.firstFinalAt ?? this.o.now();
+    const now3 = this.o.now(), lastWord = this.lastWordAt !== null;
+    const at = this.lastWordAt ?? this.firstFinalAt ?? now3;
+    const finalAt = this.finalAt || now3;
     this.firstFinalAt = null;
+    this.lastWordAt = null;
+    if (this.cur) this.close(this.cur, t.replaces === this.cur.id ? "replaced" : void 0);
     this.follow(t.text);
     this.clearProgress();
-    this.cur = { id: t.id, text: t.text, at, running: true, streamed: false, sounded: false, worded: false };
+    this.cur = { id: t.id, text: t.text, at, finalAt, lastWord, running: true, streamed: false, sounded: false, worded: false, done: false, marks: { sent: now3 }, closed: false };
+    const early = this.earlyHeard;
+    this.earlyHeard = null;
+    if (early && early.at >= at) {
+      this.cur.marks.fillAudio = early.at;
+      this.sounded(this.cur, early.by, early.at);
+    }
     this.progress.turn();
     this.o.onMetric({ name: "turn", id: t.id, kind: t.kind, text: t.text });
     this.o.sendTurn(t.text, { id: t.id, ...t.replaces ? { replaces: t.replaces } : {} });
     if (t.kind === "new") this.fill.onUserTurn(t.text);
   }
   onDrop(text, why) {
-    if (!this.gate.holding) this.firstFinalAt = null;
+    if (!this.gate.holding) {
+      this.firstFinalAt = null;
+      this.lastWordAt = null;
+      this.earlyHeard = null;
+    }
     this.o.onMetric({ name: "drop", kind: why, text });
   }
   /** Every fill/progress line passes here: only in the turn's known language, never after the call ended. */
@@ -13575,16 +13660,48 @@ var VoiceCall = class {
       return false;
     }
     if (r === false) return false;
-    this.lastAudibleAt = this.o.now();
     this.o.onMetric({ name: "fill", kind, text, lang: this.lang });
-    if (this.cur && (kind === "bridge" || kind === "progress")) this.sounded(this.cur, kind === "progress" ? "progress" : "fill");
-    else if (this.cur && this.cur.running && !this.cur.sounded && kind === "filler") this.sounded(this.cur, "fill");
+    const c = this.cur && !this.cur.closed ? this.cur : void 0;
+    const forTurn = !!c && (kind === "bridge" || kind === "progress" || kind === "filler" && c.running && !c.sounded);
+    if (c && forTurn && c.marks.fill === void 0) {
+      c.marks.fill = this.o.now();
+      c.fillKind = kind;
+    }
+    if (this.o.hostAudio) return r;
+    this.lastAudibleAt = this.o.now();
+    if (c && forTurn) {
+      c.marks.fillAudio ??= this.o.now();
+      this.sounded(c, kind === "progress" ? "progress" : "fill");
+    }
     return r;
   }
-  sounded(c, by) {
+  sounded(c, by, at = this.o.now()) {
     if (c.sounded) return;
     c.sounded = true;
-    this.o.onMetric({ name: "first_sound", id: c.id, ms: Math.round(this.o.now() - c.at), by });
+    this.o.onMetric({ name: "first_sound", id: c.id, ms: Math.round(at - c.at), by });
+  }
+  /** The turn is over (answered + audible, replaced, the next turn, the call's end): its timeline, once. A turn whose MAIN
+   *  never became audible still reports first_word — with no ms and why (cut / replaced / silent) — so every turn has one. */
+  close(c, end) {
+    if (c.closed) return;
+    c.closed = true;
+    c.end = c.worded ? "answered" : end ?? c.end ?? "silent";
+    if (!c.worded) this.o.onMetric({ name: "first_word", id: c.id, by: "main", kind: c.end });
+    const rel = (t) => t === void 0 ? void 0 : Math.round(t - c.at);
+    const m = c.marks, tl = {
+      final: rel(c.finalAt),
+      sent: rel(m.sent),
+      fill: rel(m.fill),
+      ...c.fillKind ? { fillKind: c.fillKind } : {},
+      fillAudio: rel(m.fillAudio),
+      mainFirst: rel(m.mainFirst),
+      mainText: rel(m.mainText),
+      mainAudio: rel(m.mainAudio),
+      lastWord: c.lastWord,
+      end: c.end
+    };
+    for (const k of Object.keys(tl)) if (tl[k] === void 0) delete tl[k];
+    this.o.onMetric({ name: "timeline", id: c.id, text: c.text, timeline: tl });
   }
   async onTool(c, name, args) {
     const lang = this.lang;