verbalcoding 0.2.12 → 0.2.13

package/app-node/agent_turn.mjs

@@ -0,0 +1,86 @@
+// Per-turn lifecycle helpers shared by the voice path (handleRecording)
+// and the text path (handleTextAgentMessage). Both paths used to inline
+// nearly the same controller setup + cleanup, with a subtle difference
+// in the finally block: the voice path aborted ANY currently-active
+// progress controller without confirming it was still the turn's own,
+// which Codex flagged as a race. This module centralises both ends so
+// they stay consistent.
+//
+// Usage:
+//   const lifecycle = createAgentTurnLifecycle({ bridge, warn });
+//
+//   if (bridge.processing) { /* caller handles "busy" reply */ return; }
+//   const turn = lifecycle.start({ withTurnId: true });
+//   try {
+//     // ... per-turn work using turn.signal / turn.progressController.signal ...
+//   } finally {
+//     // Optionally clear progress-speech batch first (text path does this).
+//     lifecycle.finish(turn);
+//     // Any path-specific extras (e.g. drainDeferredProcessingUtterances).
+//   }
+//
+// `withTurnId: true` opts into the voice-path semantics where
+// bridge.activeTurnId is incremented per turn and bridge.interruptedTurns
+// tracks aborts. The text path leaves turnId unset.
+
+export function createAgentTurnLifecycle(deps) {
+  const { bridge, warn } = deps;
+  // Note: clearing the progress-speech batch is intentionally NOT part of
+  // finish(). The voice path's pre-refactor cleanup did not call it; only
+  // the text path did. Callers that need it (currently
+  // handleTextAgentMessage) invoke clearProgressSpeechBatch explicitly
+  // before finish().
+
+  function start({ withTurnId = false } = {}) {
+    const controller = new AbortController();
+    bridge.currentAbortController = controller;
+    const progressController = new AbortController();
+    bridge.activeProgressAbortController = progressController;
+    bridge.activeProgressSignal = progressController.signal;
+    bridge.activeProgressLastEventAt = Date.now();
+    const previousTranscriptChannelId = bridge.activeTranscriptChannelId;
+    bridge.processing = true;
+    const turnId = withTurnId ? ++bridge.activeTurnId : undefined;
+    return {
+      controller,
+      signal: controller.signal,
+      progressController,
+      previousTranscriptChannelId,
+      turnId,
+    };
+  }
+
+  function finish(turn) {
+    if (!turn) return;
+    const { controller, progressController, previousTranscriptChannelId, turnId } = turn;
+
+    // Only abort the progress controller if it's still THIS turn's. The
+    // voice path's old inline cleanup omitted this check and could abort
+    // a newer turn's controller.
+    if (progressController
+        && bridge.activeProgressAbortController === progressController
+        && !progressController.signal.aborted) {
+      try { progressController.abort(); } catch (e) { warn?.('abort progress speech in cleanup failed', e?.stack || e); }
+    }
+    if (bridge.activeProgressAbortController === progressController) {
+      bridge.activeProgressAbortController = null;
+    }
+    if (bridge.activeProgressSignal === progressController?.signal) {
+      bridge.activeProgressSignal = null;
+    }
+
+    if (bridge.currentAbortController === controller) {
+      bridge.currentAbortController = null;
+    }
+    bridge.activeTranscriptChannelId = previousTranscriptChannelId;
+
+    if (turnId !== undefined) {
+      bridge.interruptedTurns.delete(turnId);
+      if (bridge.activeTurnId === turnId) bridge.activeTurnId = 0;
+    }
+
+    bridge.processing = false;
+  }
+
+  return { start, finish };
+}

package/app-node/agent_turn.test.mjs

@@ -0,0 +1,109 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createAgentTurnLifecycle } from './agent_turn.mjs';
+import { createBridge } from './bridge_context.mjs';
+
+const noop = () => {};
+
+function makeLifecycle(overrides = {}) {
+  const bridge = createBridge();
+  const lifecycle = createAgentTurnLifecycle({
+    bridge,
+    warn: noop,
+    ...overrides,
+  });
+  return { bridge, lifecycle };
+}
+
+test('start sets up controllers, progress signals, and processing flag', () => {
+  const { bridge, lifecycle } = makeLifecycle();
+  bridge.activeTranscriptChannelId = 'prev-ch';
+  const turn = lifecycle.start();
+  assert.ok(turn.controller instanceof AbortController);
+  assert.ok(turn.progressController instanceof AbortController);
+  assert.equal(turn.signal, turn.controller.signal);
+  assert.equal(turn.previousTranscriptChannelId, 'prev-ch');
+  assert.equal(turn.turnId, undefined, 'no turnId without withTurnId opt');
+  assert.equal(bridge.processing, true);
+  assert.equal(bridge.currentAbortController, turn.controller);
+  assert.equal(bridge.activeProgressAbortController, turn.progressController);
+  assert.equal(bridge.activeProgressSignal, turn.progressController.signal);
+  assert.ok(bridge.activeProgressLastEventAt > 0);
+});
+
+test('start with withTurnId allocates and exposes a turnId', () => {
+  const { bridge, lifecycle } = makeLifecycle();
+  const turn = lifecycle.start({ withTurnId: true });
+  assert.equal(typeof turn.turnId, 'number');
+  assert.equal(bridge.activeTurnId, turn.turnId);
+  const turn2 = lifecycle.start({ withTurnId: true });
+  assert.equal(turn2.turnId, turn.turnId + 1, 'turn ids monotonically increment');
+});
+
+test('finish clears all controllers + flags and restores transcript channel', () => {
+  const { bridge, lifecycle } = makeLifecycle();
+  bridge.activeTranscriptChannelId = 'prev-ch';
+  const turn = lifecycle.start();
+  bridge.activeTranscriptChannelId = 'turn-ch';        // simulate mutation during work
+  lifecycle.finish(turn);
+  assert.equal(bridge.processing, false);
+  assert.equal(bridge.currentAbortController, null);
+  assert.equal(bridge.activeProgressAbortController, null);
+  assert.equal(bridge.activeProgressSignal, null);
+  assert.equal(bridge.activeTranscriptChannelId, 'prev-ch', 'restored');
+  assert.equal(turn.progressController.signal.aborted, true);
+});
+
+test('finish does NOT touch the progress-speech batch (caller responsibility)', () => {
+  // Pre-refactor the voice path did not call clearProgressSpeechBatch; the
+  // text path did. The lifecycle stays path-agnostic — callers that need
+  // the batch cleared do it explicitly before finish().
+  const { bridge, lifecycle } = makeLifecycle();
+  bridge.progressSpeechBatch = ['queued event'];
+  bridge.progressSpeechBatchSignal = 'some-sig';
+  const turn = lifecycle.start();
+  lifecycle.finish(turn);
+  // Batch state preserved — caller decides when to drop it.
+  assert.deepEqual(bridge.progressSpeechBatch, ['queued event']);
+  assert.equal(bridge.progressSpeechBatchSignal, 'some-sig');
+});
+
+test('finish does NOT abort a newer turn that overrode the active progress controller', () => {
+  // This was the race Codex flagged on the voice path. We start turn A,
+  // then while A is still "in flight" we start turn B (simulating a
+  // re-entrant call); A's finish() must not abort B's progress controller.
+  const { bridge, lifecycle } = makeLifecycle();
+  const turnA = lifecycle.start();
+  // Turn B takes over (this WOULDN'T happen in practice because the
+  // processing guard prevents re-entry, but the cleanup must still be
+  // defensive against any path that leaves a stale controller in place).
+  const turnB = lifecycle.start();
+  // Now finish A. Its progressController was overridden by B; A's finish
+  // must leave B's controller alone.
+  lifecycle.finish(turnA);
+  assert.equal(bridge.activeProgressAbortController, turnB.progressController, 'B\'s progress controller untouched');
+  assert.equal(turnB.progressController.signal.aborted, false, 'B not aborted by A\'s cleanup');
+  // But A's own progressController did get aborted (it's still A's; it just wasn't bridge.active anymore).
+  // The contract is "only abort if it's the active one." A's controller is no longer active so it stays unaborted.
+  assert.equal(turnA.progressController.signal.aborted, false);
+});
+
+test('finish with withTurnId clears interruptedTurns and resets activeTurnId only when it matches', () => {
+  const { bridge, lifecycle } = makeLifecycle();
+  const turnA = lifecycle.start({ withTurnId: true });
+  bridge.interruptedTurns.add(turnA.turnId);
+  // Simulate a newer turn taking activeTurnId.
+  const turnB = lifecycle.start({ withTurnId: true });
+  lifecycle.finish(turnA);
+  assert.ok(!bridge.interruptedTurns.has(turnA.turnId), 'A removed from interruptedTurns');
+  assert.equal(bridge.activeTurnId, turnB.turnId, 'activeTurnId left as B\'s id (only resets when matching)');
+});
+
+test('finish is a no-op when passed null/undefined', () => {
+  const { bridge, lifecycle } = makeLifecycle();
+  bridge.processing = true;
+  lifecycle.finish(null);
+  lifecycle.finish(undefined);
+  // processing is unchanged because we ignored both calls
+  assert.equal(bridge.processing, true);
+});

package/app-node/bridge_context.mjs

@@ -0,0 +1,73 @@
+// Shared mutable state for the Discord voice bridge.
+//
+// main.mjs used to hold ~40 module-level `let` bindings and `Map`/`Set`
+// containers that the extracted voice_io / tts_player / utterance_router
+// modules need to read and write by reference. Wrapping them in one object
+// means every extracted module sees the same live state without having to
+// thread dozens of getters/setters through call sites.
+//
+// Fields that depend on settings/client/etc. are seeded after the caller
+// has built those (see `seedBridge`); the factory itself only allocates
+// containers and primitive defaults.
+
+export function createBridge() {
+  return {
+    // Discord client & active voice channel state
+    connection: null,
+    player: null,
+    speaking: false,
+    processing: false,
+    activeTurnId: 0,
+    activeVoiceChannelId: '',
+    activeTranscriptChannelId: '',
+    currentAbortController: null,
+    activeStreams: new Map(),
+    interruptedTurns: new Set(),
+    speechPlaybackGeneration: 0,
+    recentDiscordTextByChannel: new Map(),
+
+    // External adapters/state holders set during boot
+    ttsBackend: null,
+    bridgeState: null,
+
+    // Verbose / progress speech
+    verboseProgress: false,
+    activeProgressSignal: null,
+    verboseProgressSpeechQueue: Promise.resolve(),
+    activeProgressAbortController: null,
+    progressSpeechBatch: [],
+    progressSpeechBatchTimer: null,
+    progressSpeechBatchSignal: null,
+    progressSpeechBatchStartedAt: 0,
+    activeProgressLastEventAt: 0,
+    lastVerboseProgressText: '',
+    lastVerboseProgressTextAt: 0,
+
+    // Streaming TTS pipeline
+    activeSentencer: null,
+    activeStreamingQueue: null,
+    streamingSpeechDelivered: false,
+
+    // Notifications (ntfy/pushover)
+    notifyUserOptIn: false,
+    notifierInstance: null,
+    lastNotifyAt: 0,
+    lastNotifyBody: '',
+
+    // Plan mode / cross-agent routing / per-channel session state
+    planStates: new Map(),
+    agentAdaptersBySession: new Map(),
+    agentAdaptersByBackend: new Map(),
+    routingStateByChannel: new Map(),
+    ontologyByChannel: new Map(),
+    installedBinaryCache: new Map(),
+
+    // Barge-in sensitivity
+    sensitivityMode: 'normal',
+    sensitivityModeExpiresAt: 0,
+
+    // Smart progress summarizer
+    smartProgressEnabled: false,
+    smartProgressSummarizer: null,
+  };
+}

package/app-node/bridge_context.test.mjs

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createBridge } from './bridge_context.mjs';
+
+test('createBridge returns independent state per call', () => {
+  const a = createBridge();
+  const b = createBridge();
+  a.speaking = true;
+  a.activeStreams.set('user-1', { foo: 1 });
+  a.planStates.set('chan', { steps: [] });
+  assert.equal(b.speaking, false);
+  assert.equal(b.activeStreams.size, 0);
+  assert.equal(b.planStates.size, 0);
+});
+
+test('createBridge seeds the expected containers and primitives', () => {
+  const b = createBridge();
+  // Containers
+  for (const key of [
+    'activeStreams', 'interruptedTurns', 'recentDiscordTextByChannel',
+    'planStates', 'agentAdaptersBySession', 'agentAdaptersByBackend',
+    'routingStateByChannel', 'ontologyByChannel', 'installedBinaryCache',
+  ]) {
+    assert.ok(b[key] instanceof Map || b[key] instanceof Set, `${key} is a container`);
+    assert.equal(b[key].size, 0, `${key} starts empty`);
+  }
+  // Primitive defaults
+  assert.equal(b.connection, null);
+  assert.equal(b.player, null);
+  assert.equal(b.ttsBackend, null);
+  assert.equal(b.bridgeState, null);
+  assert.equal(b.speaking, false);
+  assert.equal(b.processing, false);
+  assert.equal(b.activeTurnId, 0);
+  assert.equal(b.activeVoiceChannelId, '');
+  assert.equal(b.activeTranscriptChannelId, '');
+  assert.equal(b.speechPlaybackGeneration, 0);
+  assert.equal(b.notifyUserOptIn, false);
+  assert.equal(b.streamingSpeechDelivered, false);
+  assert.equal(b.sensitivityMode, 'normal');
+  assert.ok(b.verboseProgressSpeechQueue instanceof Promise);
+  assert.deepEqual(b.progressSpeechBatch, []);
+});
+
+test('mutations on one bridge do not leak to another', () => {
+  const a = createBridge();
+  const b = createBridge();
+  a.routingStateByChannel.set('c1', { backend: 'codex' });
+  a.processing = true;
+  a.activeTurnId = 7;
+  assert.equal(b.routingStateByChannel.size, 0);
+  assert.equal(b.processing, false);
+  assert.equal(b.activeTurnId, 0);
+});

package/app-node/bridge_state.mjs

@@ -32,6 +32,10 @@ export function createBridgeState({ log = () => {}, cleanupFile = () => {} } = {
 
   function deletePending(userId) {
     const pending = pendingUtterances.get(userId);
+    if (pending?.timer) {
+      clearTimeout(pending.timer);
+      pending.timer = null;
+    }
     pendingUtterances.delete(userId);
     return pending;
   }