@ai-ecoverse/pi-audio 1.7.0 → 1.9.0

package/dist/turns.js

@@ -0,0 +1,347 @@
+import { VoiceRequestError } from "./errors.js";
+import { pushQueue } from "./queue.js";
+import {
+  createSpokenState,
+  spokenPieces
+} from "./spoken.js";
+function voiceTurns(models, conversation, mic, out, options, signal) {
+  const phases = pushQueue();
+  const captions = pushQueue();
+  const session = { models, conversation, mic, out, options, signal, phases, captions };
+  const done = runSession(session).finally(() => {
+    phases.end();
+    captions.end();
+  });
+  return { phases: phases.iterable, captions: captions.iterable, done };
+}
+async function runSession(session) {
+  const mode = bargeMode(session.options);
+  let active;
+  let confidence;
+  let reserved = 0;
+  let openId = "";
+  const openTurn = () => {
+    if (!openId) {
+      reserved += 1;
+      openId = String(reserved);
+    }
+    return openId;
+  };
+  const stopPlayback = session.out.onPlayback((tag) => {
+    if (!active || !("entryId" in tag.span)) return;
+    active.cut = {
+      entryId: tag.span.entryId,
+      contentIndex: tag.span.contentIndex,
+      heardUpTo: tag.span.end,
+      heardMs: session.out.playedMs
+    };
+  });
+  const setPhase = phaseSetter(session.phases);
+  try {
+    if (session.signal.aborted) return;
+    setPhase({ phase: "listening" });
+    for await (const event of session.models.listen(session.options.ears, session.mic, {
+      signal: session.signal
+    })) {
+      if (event.type === "error") {
+        if (event.reason === "aborted" || session.signal.aborted) return;
+        throw new VoiceRequestError(event.reason, event.error);
+      }
+      const captionId = event.type === "partial" || event.type === "final" || event.type === "turn_end" ? openTurn() : openId;
+      confidence = noteUser(session, event, captionId, confidence);
+      if (shouldBarge(mode, event)) active = await interrupt(session, active);
+      if (event.type !== "turn_end") continue;
+      const turnId = openId || openTurn();
+      openId = "";
+      if (mode === "ignore") active = await finishTurn(active);
+      else active = await interrupt(session, active);
+      setPhase({ phase: "heard", text: event.text });
+      const meta = turnMeta(session.options, confidence);
+      confidence = void 0;
+      active = startTurn(session, setPhase, turnId, event, meta);
+    }
+  } finally {
+    stopPlayback();
+    if (session.signal.aborted && active) await interrupt(session, active);
+    else if (active) await active.done;
+    setPhase({ phase: "idle" });
+  }
+}
+function turnMeta(options, confidence) {
+  return {
+    source: "voice",
+    transcriptionModel: options.ears.id,
+    ...confidence === void 0 ? {} : { confidence }
+  };
+}
+function noteUser(session, event, turnId, confidence) {
+  if (event.type === "partial") {
+    session.captions.push({
+      type: "user_partial",
+      turnId,
+      segmentId: event.segmentId,
+      text: event.text
+    });
+  }
+  if (event.type === "final") {
+    session.captions.push({
+      type: "user_final",
+      turnId,
+      segmentId: event.segmentId,
+      text: event.text,
+      ...event.confidence === void 0 ? {} : { confidence: event.confidence }
+    });
+    return event.confidence ?? confidence;
+  }
+  if (event.type === "turn_end") {
+    session.captions.push({ type: "user_final", turnId, segmentId: "turn", text: event.text });
+  }
+  return confidence;
+}
+async function finishTurn(active) {
+  if (!active) return void 0;
+  await active.done;
+  return void 0;
+}
+function startTurn(session, setPhase, turnId, event, meta) {
+  const linked = linkSignal(session.signal);
+  const active = {
+    controller: linked.controller,
+    unlink: linked.unlink,
+    turnId,
+    utteranceId: `${turnId}:agent`,
+    done: Promise.resolve()
+  };
+  active.done = performTurn(session, setPhase, active, event.text, event.at, meta).finally(() => {
+    linked.unlink();
+  });
+  return active;
+}
+async function performTurn(session, setPhase, active, text, at, meta) {
+  const signal = active.controller.signal;
+  try {
+    setPhase({ phase: "thinking" });
+    const message = { role: "user", content: text, timestamp: at };
+    const feed = textFeed(signal);
+    const maps = [];
+    const producing = readAgent(session, setPhase, active, message, meta, feed, maps);
+    const audio = session.models.speak(
+      session.options.mouth,
+      { text: feed.iterable, voice: session.options.voice },
+      { signal }
+    );
+    await Promise.all([producing, pipeSpeech(session, setPhase, active, audio, maps)]);
+    if (!signal.aborted) setPhase({ phase: "listening" });
+  } catch (error) {
+    if (signal.aborted || session.signal.aborted) return;
+    throw error;
+  }
+}
+async function readAgent(session, setPhase, active, message, meta, feed, maps) {
+  const state = createSpokenState();
+  let spokenChars = 0;
+  let generated = "";
+  try {
+    for await (const event of session.conversation.prompt(
+      message,
+      meta,
+      active.controller.signal
+    )) {
+      if (active.controller.signal.aborted) break;
+      notePhase(setPhase, event);
+      for (const piece of spokenPieces(event, state, session.options)) {
+        spokenChars += piece.text.length;
+        generated = rememberPiece(
+          session,
+          active,
+          piece,
+          maps,
+          spokenChars,
+          generated,
+          state.entryId
+        );
+        feed.push(piece.text);
+      }
+      if (state.entryId) bindEntry(maps, state.entryId);
+    }
+  } finally {
+    feed.end();
+  }
+}
+function rememberPiece(session, active, piece, maps, spokenEnd, generated, entryId) {
+  const bound = piece.entryId ?? entryId;
+  maps.push({
+    spokenStart: spokenEnd - piece.text.length,
+    spokenEnd,
+    contentIndex: piece.contentIndex,
+    start: piece.start,
+    end: piece.end,
+    kind: piece.kind,
+    ...bound ? { entryId: bound } : {}
+  });
+  if (piece.kind === "announce") {
+    session.captions.push({ type: "announce", turnId: active.turnId, text: piece.text });
+    return generated;
+  }
+  const text = generated + piece.text;
+  session.captions.push({
+    type: "agent_generated",
+    turnId: active.turnId,
+    utteranceId: active.utteranceId,
+    text
+  });
+  return text;
+}
+async function pipeSpeech(session, setPhase, active, audio, maps) {
+  for await (const event of audio) {
+    if (active.controller.signal.aborted) return;
+    if (event.type === "error") {
+      if (event.reason === "aborted") return;
+      throw new VoiceRequestError(event.reason, event.error);
+    }
+    if (event.type !== "audio") continue;
+    setPhase({ phase: "speaking" });
+    const span = translateSpan(event.span, maps);
+    const tag = {
+      span,
+      ...event.alignment ? { alignment: event.alignment } : {}
+    };
+    session.out.write(event.chunk, tag);
+  }
+}
+function translateSpan(span, maps) {
+  if ("entryId" in span) return span;
+  const map = answerMap(span, maps);
+  if (!map?.entryId) return span;
+  const spokenLen = map.spokenEnd - map.spokenStart;
+  const sourceLen = map.end - map.start;
+  const start = map.start + scale(Math.max(0, span.start - map.spokenStart), spokenLen, sourceLen);
+  const end = map.start + scale(Math.min(spokenLen, span.end - map.spokenStart), spokenLen, sourceLen);
+  return { entryId: map.entryId, contentIndex: map.contentIndex, start, end };
+}
+function answerMap(span, maps) {
+  for (let index = maps.length - 1; index >= 0; index -= 1) {
+    const item = maps[index];
+    if (item?.kind !== "answer" || !item.entryId) continue;
+    if (item.spokenStart < span.end && item.spokenEnd > span.start) return item;
+  }
+  return void 0;
+}
+function scale(offset, spokenLen, sourceLen) {
+  if (spokenLen <= 0) return 0;
+  return Math.round(offset * sourceLen / spokenLen);
+}
+function bindEntry(maps, entryId) {
+  for (const map of maps) {
+    if (map.kind === "answer" && map.entryId === void 0) map.entryId = entryId;
+  }
+}
+function notePhase(setPhase, event) {
+  if (event.type === "run_start" || event.type === "turn_start") setPhase({ phase: "thinking" });
+  if (event.type === "compaction_start") setPhase({ phase: "compacting" });
+  if (event.type === "auto_retry_start" && event.attempt !== void 0 && event.at !== void 0) {
+    setPhase({ phase: "retrying", attempt: event.attempt, at: event.at });
+  }
+  if (event.type === "tool_execution_start" && event.toolName && event.toolCallId) {
+    setPhase({
+      phase: "tool",
+      toolName: event.toolName,
+      toolCallId: event.toolCallId,
+      args: event.args ?? {}
+    });
+  }
+}
+async function interrupt(session, active) {
+  if (!active) return void 0;
+  active.controller.abort();
+  session.out.flush();
+  await active.done;
+  if (active.cut) {
+    session.captions.push({
+      type: "agent_cut",
+      turnId: active.turnId,
+      utteranceId: active.utteranceId,
+      heardUpTo: active.cut.heardUpTo
+    });
+    await session.conversation.truncate(active.cut);
+  }
+  return void 0;
+}
+function bargeMode(options) {
+  const mode = options.bargeIn ?? "interrupt";
+  if (mode !== "auto") return mode;
+  if (options.echoRecommendation === "interrupt") return "interrupt";
+  if (options.echoRecommendation === "headphones") return "ignore";
+  return "onWords";
+}
+function shouldBarge(mode, event) {
+  if (mode === "ignore") return false;
+  if (mode === "interrupt") return event.type === "speech_start";
+  return event.type === "partial" && event.text.trim().length > 0;
+}
+function phaseSetter(phases) {
+  let previous = "";
+  return (phase) => {
+    const key = JSON.stringify(phase);
+    if (key === previous) return;
+    previous = key;
+    phases.push(phase);
+  };
+}
+function linkSignal(parent) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (parent.aborted) controller.abort();
+  else parent.addEventListener("abort", abort);
+  return {
+    controller,
+    unlink: () => parent.removeEventListener("abort", abort)
+  };
+}
+function textFeed(signal) {
+  const queue = [];
+  let ended = false;
+  let wake;
+  const notify = () => {
+    const current = wake;
+    wake = void 0;
+    current?.();
+  };
+  const onAbort = () => notify();
+  signal.addEventListener("abort", onAbort);
+  return {
+    push(text) {
+      if (ended || signal.aborted || text.length === 0) return;
+      queue.push(text);
+      notify();
+    },
+    end() {
+      ended = true;
+      notify();
+    },
+    iterable: {
+      async *[Symbol.asyncIterator]() {
+        try {
+          while (!signal.aborted) {
+            const next = queue.shift();
+            if (next !== void 0) {
+              yield next;
+              continue;
+            }
+            if (ended) return;
+            await new Promise((resolve) => {
+              if (queue.length > 0 || ended || signal.aborted) resolve();
+              else wake = resolve;
+            });
+          }
+        } finally {
+          signal.removeEventListener("abort", onAbort);
+        }
+      }
+    }
+  };
+}
+export {
+  voiceTurns
+};
+//# sourceMappingURL=turns.js.map

package/dist/turns.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/turns.ts"],
+  "sourcesContent": ["import type {\n  AssistantMessageEvent,\n  JsonObject,\n  ProviderRequestOptions,\n  ToolCall,\n  UserMessage,\n} from '@earendil-works/pi-ai';\nimport type { AudioSink, AudioSource, AudioTag, TextSpan } from './audio.ts';\nimport { VoiceRequestError } from './errors.ts';\nimport type { SpeechModel, TranscriptionModel } from './models.ts';\nimport { pushQueue } from './queue.ts';\nimport type { SpeechEvent, SpeechInput } from './speech.ts';\nimport {\n  createSpokenState,\n  type SpokenPiece,\n  spokenPieces,\n  type VoiceAgentEvent,\n} from './spoken.ts';\nimport type { ListenOptions, TranscriptionEvent } from './transcription.ts';\n\nexport interface VoiceTurnMeta {\n  source: 'voice';\n  transcriptionModel: string;\n  confidence?: number;\n}\n\nexport interface VoiceCut {\n  entryId: string;\n  contentIndex: number;\n  heardUpTo: number;\n  heardMs: number;\n}\n\nexport interface VoiceConversation {\n  prompt(\n    message: UserMessage,\n    meta: VoiceTurnMeta,\n    signal: AbortSignal\n  ): AsyncIterable<VoiceAgentEvent>;\n  truncate(cut: VoiceCut): Promise<void>;\n}\n\nexport type BargeIn = 'interrupt' | 'onWords' | 'ignore' | 'auto';\n\nexport type EchoRecommendation = 'interrupt' | 'onWords' | 'headphones';\n\nexport interface VoiceTurnOptions {\n  ears: TranscriptionModel<string>;\n  mouth: SpeechModel<string>;\n  voice: string;\n  speakable?: (event: AssistantMessageEvent) => string | undefined;\n  announce?: (call: ToolCall) => string | undefined;\n  bargeIn?: BargeIn;\n  echoRecommendation?: EchoRecommendation;\n}\n\nexport interface VoiceModels {\n  listen(\n    model: TranscriptionModel<string>,\n    audio: AudioSource,\n    options?: ListenOptions\n  ): AsyncIterable<TranscriptionEvent>;\n  speak(\n    model: SpeechModel<string>,\n    input: SpeechInput,\n    options?: ProviderRequestOptions\n  ): AsyncIterable<SpeechEvent>;\n}\n\nexport type VoicePhase =\n  | { phase: 'listening' }\n  | { phase: 'heard'; text: string }\n  | { phase: 'thinking' }\n  | { phase: 'tool'; toolName: string; toolCallId: string; args: JsonObject }\n  | { phase: 'retrying'; attempt: number; at: number }\n  | { phase: 'compacting' }\n  | { phase: 'speaking' }\n  | { phase: 'idle' };\n\nexport type CaptionEvent =\n  | { type: 'user_partial'; turnId: string; segmentId: string; text: string }\n  | { type: 'user_final'; turnId: string; segmentId: string; text: string; confidence?: number }\n  | { type: 'agent_generated'; turnId: string; utteranceId: string; text: string }\n  | { type: 'agent_spoken'; turnId: string; utteranceId: string; upTo: number }\n  | { type: 'agent_cut'; turnId: string; utteranceId: string; heardUpTo: number }\n  | { type: 'announce'; turnId: string; text: string }\n  | { type: 'thinker_progress'; turnId: string; callId: string; text: string }\n  | { type: 'thinker_result'; turnId: string; callId: string; summary: string; isError: boolean };\n\nexport interface VoiceSession {\n  phases: AsyncIterable<VoicePhase>;\n  captions: AsyncIterable<CaptionEvent>;\n  done: Promise<void>;\n}\n\ninterface SpokenMap {\n  spokenStart: number;\n  spokenEnd: number;\n  contentIndex: number;\n  start: number;\n  end: number;\n  entryId?: string;\n  kind: SpokenPiece['kind'];\n}\n\ninterface ActiveTurn {\n  controller: AbortController;\n  unlink: () => void;\n  done: Promise<void>;\n  turnId: string;\n  utteranceId: string;\n  cut?: VoiceCut;\n}\n\nexport function voiceTurns(\n  models: VoiceModels,\n  conversation: VoiceConversation,\n  mic: AudioSource,\n  out: AudioSink,\n  options: VoiceTurnOptions,\n  signal: AbortSignal\n): VoiceSession {\n  const phases = pushQueue<VoicePhase>();\n  const captions = pushQueue<CaptionEvent>();\n  const session: Session = { models, conversation, mic, out, options, signal, phases, captions };\n  const done = runSession(session).finally(() => {\n    phases.end();\n    captions.end();\n  });\n  return { phases: phases.iterable, captions: captions.iterable, done };\n}\n\ninterface Session {\n  models: VoiceModels;\n  conversation: VoiceConversation;\n  mic: AudioSource;\n  out: AudioSink;\n  options: VoiceTurnOptions;\n  signal: AbortSignal;\n  phases: ReturnType<typeof pushQueue<VoicePhase>>;\n  captions: ReturnType<typeof pushQueue<CaptionEvent>>;\n}\n\nasync function runSession(session: Session): Promise<void> {\n  const mode = bargeMode(session.options);\n  let active: ActiveTurn | undefined;\n  let confidence: number | undefined;\n  let reserved = 0;\n  let openId = '';\n  const openTurn = () => {\n    if (!openId) {\n      reserved += 1;\n      openId = String(reserved);\n    }\n    return openId;\n  };\n  const stopPlayback = session.out.onPlayback((tag) => {\n    if (!active || !('entryId' in tag.span)) return;\n    active.cut = {\n      entryId: tag.span.entryId,\n      contentIndex: tag.span.contentIndex,\n      heardUpTo: tag.span.end,\n      heardMs: session.out.playedMs,\n    };\n  });\n  const setPhase = phaseSetter(session.phases);\n  try {\n    if (session.signal.aborted) return;\n    setPhase({ phase: 'listening' });\n    for await (const event of session.models.listen(session.options.ears, session.mic, {\n      signal: session.signal,\n    })) {\n      if (event.type === 'error') {\n        if (event.reason === 'aborted' || session.signal.aborted) return;\n        throw new VoiceRequestError(event.reason, event.error);\n      }\n      const captionId =\n        event.type === 'partial' || event.type === 'final' || event.type === 'turn_end'\n          ? openTurn()\n          : openId;\n      confidence = noteUser(session, event, captionId, confidence);\n      if (shouldBarge(mode, event)) active = await interrupt(session, active);\n      if (event.type !== 'turn_end') continue;\n      const turnId = openId || openTurn();\n      openId = '';\n      if (mode === 'ignore') active = await finishTurn(active);\n      else active = await interrupt(session, active);\n      setPhase({ phase: 'heard', text: event.text });\n      const meta = turnMeta(session.options, confidence);\n      confidence = undefined;\n      active = startTurn(session, setPhase, turnId, event, meta);\n    }\n  } finally {\n    stopPlayback();\n    if (session.signal.aborted && active) await interrupt(session, active);\n    else if (active) await active.done;\n    setPhase({ phase: 'idle' });\n  }\n}\n\nfunction turnMeta(options: VoiceTurnOptions, confidence: number | undefined): VoiceTurnMeta {\n  return {\n    source: 'voice',\n    transcriptionModel: options.ears.id,\n    ...(confidence === undefined ? {} : { confidence }),\n  };\n}\n\nfunction noteUser(\n  session: Session,\n  event: TranscriptionEvent,\n  turnId: string,\n  confidence: number | undefined\n): number | undefined {\n  if (event.type === 'partial') {\n    session.captions.push({\n      type: 'user_partial',\n      turnId,\n      segmentId: event.segmentId,\n      text: event.text,\n    });\n  }\n  if (event.type === 'final') {\n    session.captions.push({\n      type: 'user_final',\n      turnId,\n      segmentId: event.segmentId,\n      text: event.text,\n      ...(event.confidence === undefined ? {} : { confidence: event.confidence }),\n    });\n    return event.confidence ?? confidence;\n  }\n  if (event.type === 'turn_end') {\n    session.captions.push({ type: 'user_final', turnId, segmentId: 'turn', text: event.text });\n  }\n  return confidence;\n}\n\nasync function finishTurn(active: ActiveTurn | undefined): Promise<undefined> {\n  if (!active) return undefined;\n  await active.done;\n  return undefined;\n}\n\nfunction startTurn(\n  session: Session,\n  setPhase: (phase: VoicePhase) => void,\n  turnId: string,\n  event: Extract<TranscriptionEvent, { type: 'turn_end' }>,\n  meta: VoiceTurnMeta\n): ActiveTurn {\n  const linked = linkSignal(session.signal);\n  const active: ActiveTurn = {\n    controller: linked.controller,\n    unlink: linked.unlink,\n    turnId,\n    utteranceId: `${turnId}:agent`,\n    done: Promise.resolve(),\n  };\n  active.done = performTurn(session, setPhase, active, event.text, event.at, meta).finally(() => {\n    linked.unlink();\n  });\n  return active;\n}\n\nasync function performTurn(\n  session: Session,\n  setPhase: (phase: VoicePhase) => void,\n  active: ActiveTurn,\n  text: string,\n  at: number,\n  meta: VoiceTurnMeta\n): Promise<void> {\n  const signal = active.controller.signal;\n  try {\n    setPhase({ phase: 'thinking' });\n    const message: UserMessage = { role: 'user', content: text, timestamp: at };\n    const feed = textFeed(signal);\n    const maps: SpokenMap[] = [];\n    const producing = readAgent(session, setPhase, active, message, meta, feed, maps);\n    const audio = session.models.speak(\n      session.options.mouth,\n      { text: feed.iterable, voice: session.options.voice },\n      { signal }\n    );\n    await Promise.all([producing, pipeSpeech(session, setPhase, active, audio, maps)]);\n    if (!signal.aborted) setPhase({ phase: 'listening' });\n  } catch (error) {\n    if (signal.aborted || session.signal.aborted) return;\n    throw error;\n  }\n}\n\nasync function readAgent(\n  session: Session,\n  setPhase: (phase: VoicePhase) => void,\n  active: ActiveTurn,\n  message: UserMessage,\n  meta: VoiceTurnMeta,\n  feed: TextFeed,\n  maps: SpokenMap[]\n): Promise<void> {\n  const state = createSpokenState();\n  let spokenChars = 0;\n  let generated = '';\n  try {\n    for await (const event of session.conversation.prompt(\n      message,\n      meta,\n      active.controller.signal\n    )) {\n      if (active.controller.signal.aborted) break;\n      notePhase(setPhase, event);\n      for (const piece of spokenPieces(event, state, session.options)) {\n        spokenChars += piece.text.length;\n        generated = rememberPiece(\n          session,\n          active,\n          piece,\n          maps,\n          spokenChars,\n          generated,\n          state.entryId\n        );\n        feed.push(piece.text);\n      }\n      if (state.entryId) bindEntry(maps, state.entryId);\n    }\n  } finally {\n    feed.end();\n  }\n}\n\nfunction rememberPiece(\n  session: Session,\n  active: ActiveTurn,\n  piece: SpokenPiece,\n  maps: SpokenMap[],\n  spokenEnd: number,\n  generated: string,\n  entryId: string | undefined\n): string {\n  const bound = piece.entryId ?? entryId;\n  maps.push({\n    spokenStart: spokenEnd - piece.text.length,\n    spokenEnd,\n    contentIndex: piece.contentIndex,\n    start: piece.start,\n    end: piece.end,\n    kind: piece.kind,\n    ...(bound ? { entryId: bound } : {}),\n  });\n  if (piece.kind === 'announce') {\n    session.captions.push({ type: 'announce', turnId: active.turnId, text: piece.text });\n    return generated;\n  }\n  const text = generated + piece.text;\n  session.captions.push({\n    type: 'agent_generated',\n    turnId: active.turnId,\n    utteranceId: active.utteranceId,\n    text,\n  });\n  return text;\n}\n\nasync function pipeSpeech(\n  session: Session,\n  setPhase: (phase: VoicePhase) => void,\n  active: ActiveTurn,\n  audio: AsyncIterable<SpeechEvent>,\n  maps: SpokenMap[]\n): Promise<void> {\n  for await (const event of audio) {\n    if (active.controller.signal.aborted) return;\n    if (event.type === 'error') {\n      if (event.reason === 'aborted') return;\n      throw new VoiceRequestError(event.reason, event.error);\n    }\n    if (event.type !== 'audio') continue;\n    setPhase({ phase: 'speaking' });\n    const span = translateSpan(event.span, maps);\n    const tag: AudioTag = {\n      span,\n      ...(event.alignment ? { alignment: event.alignment } : {}),\n    };\n    session.out.write(event.chunk, tag);\n  }\n}\n\nfunction translateSpan(span: TextSpan, maps: SpokenMap[]): TextSpan {\n  if ('entryId' in span) return span;\n  const map = answerMap(span, maps);\n  if (!map?.entryId) return span;\n  const spokenLen = map.spokenEnd - map.spokenStart;\n  const sourceLen = map.end - map.start;\n  const start = map.start + scale(Math.max(0, span.start - map.spokenStart), spokenLen, sourceLen);\n  const end =\n    map.start + scale(Math.min(spokenLen, span.end - map.spokenStart), spokenLen, sourceLen);\n  return { entryId: map.entryId, contentIndex: map.contentIndex, start, end };\n}\n\nfunction answerMap(span: { start: number; end: number }, maps: SpokenMap[]): SpokenMap | undefined {\n  for (let index = maps.length - 1; index >= 0; index -= 1) {\n    const item = maps[index];\n    if (item?.kind !== 'answer' || !item.entryId) continue;\n    if (item.spokenStart < span.end && item.spokenEnd > span.start) return item;\n  }\n  return undefined;\n}\n\nfunction scale(offset: number, spokenLen: number, sourceLen: number): number {\n  if (spokenLen <= 0) return 0;\n  return Math.round((offset * sourceLen) / spokenLen);\n}\n\nfunction bindEntry(maps: SpokenMap[], entryId: string): void {\n  for (const map of maps) {\n    if (map.kind === 'answer' && map.entryId === undefined) map.entryId = entryId;\n  }\n}\n\nfunction notePhase(setPhase: (phase: VoicePhase) => void, event: VoiceAgentEvent): void {\n  if (event.type === 'run_start' || event.type === 'turn_start') setPhase({ phase: 'thinking' });\n  if (event.type === 'compaction_start') setPhase({ phase: 'compacting' });\n  if (event.type === 'auto_retry_start' && event.attempt !== undefined && event.at !== undefined) {\n    setPhase({ phase: 'retrying', attempt: event.attempt, at: event.at });\n  }\n  if (event.type === 'tool_execution_start' && event.toolName && event.toolCallId) {\n    setPhase({\n      phase: 'tool',\n      toolName: event.toolName,\n      toolCallId: event.toolCallId,\n      args: event.args ?? {},\n    });\n  }\n}\n\nasync function interrupt(session: Session, active: ActiveTurn | undefined): Promise<undefined> {\n  if (!active) return undefined;\n  active.controller.abort();\n  session.out.flush();\n  await active.done;\n  if (active.cut) {\n    session.captions.push({\n      type: 'agent_cut',\n      turnId: active.turnId,\n      utteranceId: active.utteranceId,\n      heardUpTo: active.cut.heardUpTo,\n    });\n    await session.conversation.truncate(active.cut);\n  }\n  return undefined;\n}\n\nfunction bargeMode(options: VoiceTurnOptions): 'interrupt' | 'onWords' | 'ignore' {\n  const mode = options.bargeIn ?? 'interrupt';\n  if (mode !== 'auto') return mode;\n  if (options.echoRecommendation === 'interrupt') return 'interrupt';\n  if (options.echoRecommendation === 'headphones') return 'ignore';\n  return 'onWords';\n}\n\nfunction shouldBarge(mode: 'interrupt' | 'onWords' | 'ignore', event: TranscriptionEvent): boolean {\n  if (mode === 'ignore') return false;\n  if (mode === 'interrupt') return event.type === 'speech_start';\n  return event.type === 'partial' && event.text.trim().length > 0;\n}\n\nfunction phaseSetter(phases: Session['phases']): (phase: VoicePhase) => void {\n  let previous = '';\n  return (phase) => {\n    const key = JSON.stringify(phase);\n    if (key === previous) return;\n    previous = key;\n    phases.push(phase);\n  };\n}\n\nfunction linkSignal(parent: AbortSignal): { controller: AbortController; unlink: () => void } {\n  const controller = new AbortController();\n  const abort = () => controller.abort();\n  if (parent.aborted) controller.abort();\n  else parent.addEventListener('abort', abort);\n  return {\n    controller,\n    unlink: () => parent.removeEventListener('abort', abort),\n  };\n}\n\ninterface TextFeed {\n  push(text: string): void;\n  end(): void;\n  iterable: AsyncIterable<string>;\n}\n\nfunction textFeed(signal: AbortSignal): TextFeed {\n  const queue: string[] = [];\n  let ended = false;\n  let wake: (() => void) | undefined;\n  const notify = () => {\n    const current = wake;\n    wake = undefined;\n    current?.();\n  };\n  const onAbort = () => notify();\n  signal.addEventListener('abort', onAbort);\n  return {\n    push(text) {\n      if (ended || signal.aborted || text.length === 0) return;\n      queue.push(text);\n      notify();\n    },\n    end() {\n      ended = true;\n      notify();\n    },\n    iterable: {\n      async *[Symbol.asyncIterator]() {\n        try {\n          while (!signal.aborted) {\n            const next = queue.shift();\n            if (next !== undefined) {\n              yield next;\n              continue;\n            }\n            if (ended) return;\n            await new Promise<void>((resolve) => {\n              if (queue.length > 0 || ended || signal.aborted) resolve();\n              else wake = resolve;\n            });\n          }\n        } finally {\n          signal.removeEventListener('abort', onAbort);\n        }\n      },\n    },\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/types/index.d.ts

@@ -10,10 +10,13 @@ export { planDelivery, planTruncation, RealtimeLedger, realtimeSocket } from './
 export { connectRealtime, listen, registerRealtimeApiProvider, registerSpeechApiProvider, registerTranscriptionApiProvider, speak, transcribe, } from './registry.ts';
 export type { SpeechApiProvider, SpeechEvent, SpeechInput } from './speech.ts';
 export { SpeechEventStream } from './speech.ts';
+export type { VoiceAgentEvent, VoiceMessageChange } from './spoken.ts';
 export type { BindThinkerOptions, BoundThinker, Thinker, ThinkerCaption, ThinkerPhase, ThinkerUpdate, } from './talker.ts';
 export { askAgent, bindThinker, talkerTools } from './talker.ts';
 export type { AudioInput, ListenOptions, Transcript, TranscriptionApiProvider, TranscriptionEvent, TranscriptSegment, } from './transcription.ts';
 export { TranscriptionEventStream } from './transcription.ts';
+export type { BargeIn, CaptionEvent, EchoRecommendation, VoiceConversation, VoiceCut, VoiceModels, VoicePhase, VoiceSession, VoiceTurnMeta, VoiceTurnOptions, } from './turns.ts';
+export { voiceTurns } from './turns.ts';
 export type { AudioCost, AudioCounters, AudioUsage, RealtimeAudioCost, SpeechAudioCost, TranscriptionAudioCost, } from './usage.ts';
 export { addAudioCounters, priceAudio } from './usage.ts';
 export type { VadHook, VadUpdate } from './vad.ts';

package/dist/types/openai-realtime/index.d.ts

@@ -0,0 +1,7 @@
+import type { RealtimeModel } from '../models.ts';
+import { type AdapterOptions } from './session.ts';
+export declare const gptRealtime2: RealtimeModel<"openai-realtime">;
+export declare const gptRealtime21: RealtimeModel<"openai-realtime">;
+export declare function registerOpenAIRealtime(options?: AdapterOptions): () => void;
+export type { AdapterOptions, VoiceWireFactory } from './session.ts';
+export type { VoiceSocketConstructor, VoiceWire, VoiceWireTarget } from './socket.ts';

package/dist/types/openai-realtime/session.d.ts

@@ -0,0 +1,15 @@
+import type { AudioFormat } from '../audio.ts';
+import type { RealtimeModel } from '../models.ts';
+import type { RealtimeContext, RealtimeOptions, RealtimeSession } from '../realtime.ts';
+import { type VoiceSocketConstructor, type VoiceWire, type VoiceWireTarget } from './socket.ts';
+export type VoiceWireFactory = (target: VoiceWireTarget) => VoiceWire;
+export interface AdapterOptions {
+    wire?: VoiceWireFactory;
+    socket?: VoiceSocketConstructor;
+    replace?: Record<string, string>;
+}
+export interface VendorSessionOptions extends AdapterOptions {
+    dialect: 'openai' | 'xai';
+}
+export declare function connectVendorSession(model: RealtimeModel<string>, context: RealtimeContext, options: RealtimeOptions | undefined, vendor: VendorSessionOptions): Promise<RealtimeSession>;
+export declare function pcmFormat(sampleRate: number): AudioFormat;

package/dist/types/openai-realtime/socket.d.ts

@@ -0,0 +1,25 @@
+export interface VoiceWireTarget {
+    url: string;
+    protocols: string[];
+    headers: Record<string, string>;
+}
+export interface VoiceWire {
+    send(data: string): void;
+    close(): void;
+    incoming: AsyncIterable<string>;
+}
+export interface VoiceSocket {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: () => void): void;
+    addEventListener(type: 'error', listener: () => void): void;
+}
+export type VoiceSocketInit = {
+    protocols: string[];
+    headers: Record<string, string>;
+};
+export type VoiceSocketConstructor = new (url: string, init: VoiceSocketInit) => VoiceSocket;
+export declare function openVoiceSocket(target: VoiceWireTarget, Socket?: VoiceSocketConstructor): VoiceWire;

package/dist/types/queue.d.ts

@@ -0,0 +1,6 @@
+export interface PushQueue<T> {
+    push(value: T): void;
+    end(): void;
+    readonly iterable: AsyncIterable<T>;
+}
+export declare function pushQueue<T>(): PushQueue<T>;

package/dist/types/spoken.d.ts

@@ -0,0 +1,57 @@
+import type { AssistantMessage, AssistantMessageEvent, JsonObject, TextContent, ThinkingContent, ToolCall } from '@earendil-works/pi-ai';
+export interface VoiceMessageChange {
+    type: string;
+    contentIndex?: number;
+    delta?: string;
+    block?: TextContent | ThinkingContent | ToolCall;
+    message?: AssistantMessage;
+}
+export interface VoiceEntryRef {
+    id: string | number;
+    model?: readonly {
+        role: string;
+        content?: readonly (TextContent | ThinkingContent | ToolCall)[];
+    }[];
+}
+export interface VoiceAgentEvent {
+    type: string;
+    changes?: readonly VoiceMessageChange[];
+    message?: {
+        role: string;
+        content?: unknown;
+    };
+    entry?: VoiceEntryRef;
+    toolName?: string;
+    toolCallId?: string;
+    args?: JsonObject;
+    attempt?: number;
+    at?: number;
+}
+export interface SpokenPiece {
+    text: string;
+    contentIndex: number;
+    start: number;
+    end: number;
+    kind: 'answer' | 'announce';
+    entryId?: string;
+}
+interface BlockTrack {
+    kind: 'text' | 'thinking' | 'tool';
+    text: string;
+    sent: number;
+    signature?: string;
+    ended: boolean;
+}
+export interface SpokenState {
+    blocks: Map<number, BlockTrack>;
+    entryId?: string;
+}
+export interface SpokenOptions {
+    speakable?(event: AssistantMessageEvent): string | undefined;
+    announce?(call: ToolCall): string | undefined;
+    model?: string;
+}
+export declare function createSpokenState(): SpokenState;
+export declare function isCommentary(signature: string | undefined): boolean;
+export declare function spokenPieces(event: VoiceAgentEvent, state: SpokenState, options?: SpokenOptions): SpokenPiece[];
+export {};

package/dist/types/turns.d.ts

@@ -0,0 +1,107 @@
+import type { AssistantMessageEvent, JsonObject, ProviderRequestOptions, ToolCall, UserMessage } from '@earendil-works/pi-ai';
+import type { AudioSink, AudioSource } from './audio.ts';
+import type { SpeechModel, TranscriptionModel } from './models.ts';
+import type { SpeechEvent, SpeechInput } from './speech.ts';
+import { type VoiceAgentEvent } from './spoken.ts';
+import type { ListenOptions, TranscriptionEvent } from './transcription.ts';
+export interface VoiceTurnMeta {
+    source: 'voice';
+    transcriptionModel: string;
+    confidence?: number;
+}
+export interface VoiceCut {
+    entryId: string;
+    contentIndex: number;
+    heardUpTo: number;
+    heardMs: number;
+}
+export interface VoiceConversation {
+    prompt(message: UserMessage, meta: VoiceTurnMeta, signal: AbortSignal): AsyncIterable<VoiceAgentEvent>;
+    truncate(cut: VoiceCut): Promise<void>;
+}
+export type BargeIn = 'interrupt' | 'onWords' | 'ignore' | 'auto';
+export type EchoRecommendation = 'interrupt' | 'onWords' | 'headphones';
+export interface VoiceTurnOptions {
+    ears: TranscriptionModel<string>;
+    mouth: SpeechModel<string>;
+    voice: string;
+    speakable?: (event: AssistantMessageEvent) => string | undefined;
+    announce?: (call: ToolCall) => string | undefined;
+    bargeIn?: BargeIn;
+    echoRecommendation?: EchoRecommendation;
+}
+export interface VoiceModels {
+    listen(model: TranscriptionModel<string>, audio: AudioSource, options?: ListenOptions): AsyncIterable<TranscriptionEvent>;
+    speak(model: SpeechModel<string>, input: SpeechInput, options?: ProviderRequestOptions): AsyncIterable<SpeechEvent>;
+}
+export type VoicePhase = {
+    phase: 'listening';
+} | {
+    phase: 'heard';
+    text: string;
+} | {
+    phase: 'thinking';
+} | {
+    phase: 'tool';
+    toolName: string;
+    toolCallId: string;
+    args: JsonObject;
+} | {
+    phase: 'retrying';
+    attempt: number;
+    at: number;
+} | {
+    phase: 'compacting';
+} | {
+    phase: 'speaking';
+} | {
+    phase: 'idle';
+};
+export type CaptionEvent = {
+    type: 'user_partial';
+    turnId: string;
+    segmentId: string;
+    text: string;
+} | {
+    type: 'user_final';
+    turnId: string;
+    segmentId: string;
+    text: string;
+    confidence?: number;
+} | {
+    type: 'agent_generated';
+    turnId: string;
+    utteranceId: string;
+    text: string;
+} | {
+    type: 'agent_spoken';
+    turnId: string;
+    utteranceId: string;
+    upTo: number;
+} | {
+    type: 'agent_cut';
+    turnId: string;
+    utteranceId: string;
+    heardUpTo: number;
+} | {
+    type: 'announce';
+    turnId: string;
+    text: string;
+} | {
+    type: 'thinker_progress';
+    turnId: string;
+    callId: string;
+    text: string;
+} | {
+    type: 'thinker_result';
+    turnId: string;
+    callId: string;
+    summary: string;
+    isError: boolean;
+};
+export interface VoiceSession {
+    phases: AsyncIterable<VoicePhase>;
+    captions: AsyncIterable<CaptionEvent>;
+    done: Promise<void>;
+}
+export declare function voiceTurns(models: VoiceModels, conversation: VoiceConversation, mic: AudioSource, out: AudioSink, options: VoiceTurnOptions, signal: AbortSignal): VoiceSession;

package/dist/types/xai/index.d.ts

@@ -0,0 +1,4 @@
+import type { RealtimeModel } from '../models.ts';
+import { type AdapterOptions } from '../openai-realtime/session.ts';
+export declare const grokVoiceLatest: RealtimeModel<'xai-realtime'>;
+export declare function registerXaiRealtime(options?: AdapterOptions): () => void;