Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

11.2 KB
Raw Blame
import type { VoiceCallRecord } from '@cindy/maker-core';
export type { VoiceCallRecord } from '@cindy/maker-core';
import type { AudioTrace, ConversationInputEvent } from '@cindy/voice-input-core';
import type { AgentKind } from '@cindy/model-providers';
import type { AgentRequestReceipt } from './forwardedRequest.js';

/** Display-only recognition of the existing host-generated dispatch id and
 * protected source receipt. Never use this marker as permission or acceptance.
 * It works even when the call card is outside the current history page. */
export function isVoiceCallTaskMessage(
  clientId: string,
  sessionId: string,
  text: string,
  receipt: unknown,
): boolean {
  if (!receipt || typeof receipt !== 'object') return false;
  const candidate = receipt as Partial<AgentRequestReceipt>;
  const source = candidate.kind === 'agent-request' ? candidate.request : undefined;
  if (typeof source?.clientId !== 'string' || !source.clientId
    || source.sessionId !== sessionId || source.userText !== text) return false;
  const prefix = 'voice-task:';
  const suffix = `:${source.clientId}`;
  return clientId.startsWith(prefix) && clientId.endsWith(suffix)
    && clientId.length > prefix.length + suffix.length;
}

/** Persisted metadata can come from an older or incomplete history projection. */
export function readVoiceCallRecord(value: unknown): VoiceCallRecord | null {
  if (!value || typeof value !== 'object') return null;
  const record = value as Partial<VoiceCallRecord>;
  if (record.version !== 1 || typeof record.callId !== 'string'
    || !Number.isFinite(record.startedAt)
    || (record.endedAt !== undefined && !Number.isFinite(record.endedAt))
    || !Array.isArray(record.turns) || record.turns.length > 2_000
    || !Array.isArray(record.handoffs) || record.handoffs.length > 2_000) return null;
  if (!record.turns.every(turn => turn && typeof turn.id === 'string'
    && (turn.role === 'user' || turn.role === 'assistant') && typeof turn.text === 'string'
    && Number.isFinite(turn.createdAt) && typeof turn.complete === 'boolean')) return null;
  if (!record.handoffs.every(task => task && typeof task.id === 'string'
    && typeof task.inputId === 'string' && typeof task.text === 'string'
    && ['sending', 'accepted', 'failed', 'completed'].includes(task.state))) return null;
  return record as VoiceCallRecord;
}

/** Call-local exit decision, observed alongside normal message dispatch.
 * true offers a cancellable countdown after acceptance; submit_then_exit closes
 * immediately after acceptance. Neither result retracts or resends the message.
 * Keep boolean outcomes for local bridge/test compatibility. */
export type VoiceExitDecision = boolean | 'submit_then_exit';

export { speechSpeedRange, isSpeechSpeedSupported, resolveSpeechSpeed } from './speechProtocols.js';
export type { SpeechProtocol } from './speechProtocols.js';
import { SPEECH_PROTOCOLS, type SpeechProtocol, type SpeechSpeedRange } from './speechProtocols.js';

// Missing provider/runtime is the original Cindy AI selection, never another connection.
export type SpeechModelSelection = {
  providerId?: string;
  agent?: AgentKind;
  modelId: string;
  /** Custom endpoints allow overrides; official endpoints always use their own adapter. */
  protocol?: SpeechProtocol;
};
export type VoiceConversationSelection = SpeechModelSelection & {
  voice: string;
  /** Explicit per-companion synthesis speed. Absent keeps the provider default (1×). */
  speed?: number;
};
export type SpeechVoice = { id: string; name: string };
export type SpeechVoiceCatalog = {
  voices: SpeechVoice[];
  /** References are model-specific suggestions, not proof a compatible proxy supports them. */
  source: 'provider' | 'reference' | 'mixed' | 'manual';
  truncated?: boolean;
  /** Public references and verified entries remain usable after a partial private lookup. */
  customVoicesUnavailable?: boolean;
};
export type SpeechPreviewStart = VoiceConversationSelection & {
  previewId: string;
  botId: string;
  sessionId: string;
  text: string;
};
export type VoiceConversationModel = {
  /** Display preference only; hidden routes remain available for saved selections. */
  pickerVisible?: boolean;
  id: string;
  name: string;
  providerId?: string;
  providerName?: string;
  agent?: AgentKind;
  protocol?: SpeechProtocol;
  /** The official endpoint fixes protocol; saved overrides cannot select another adapter. */
  protocolLocked?: boolean;
  /** Host-owned route capability. Absent uses protocol defaults; null omits speed.
   * Display only, never persisted or accepted as a caller-provided capability. */
  speedRange?: SpeechSpeedRange;
  defaultVoice?: string;
};
export type VoiceConversationPreference = {
  selection: VoiceConversationSelection | null;
  customized: boolean;
  /** Absent on older local bridges; the current default is enabled. */
  sentencePlayback?: boolean;
};
/** Local-only synthesis result. PCM remains pull-driven; encoded segments are
 * received during bounded prefetch and decoded by the sandboxed audio player. */
export type EncodedSpeechAudio = { format: 'mp3'; data: ArrayBuffer };
export type SpeechAudioResult = { sampleRate: number } | EncodedSpeechAudio;
export const MAX_ENCODED_SPEECH_BYTES = 8 * 1024 * 1024;
export type SpeechStartResult = SpeechAudioResult | { deferred: true };
export function voiceModelKey(model: {
  providerId?: string;
  agent?: AgentKind;
  modelId?: string;
  id?: string;
}): string {
  return JSON.stringify([model.providerId ?? 'xd', model.agent ?? '', model.modelId ?? model.id]);
}
export type VoiceConversationEvent = {
  callId: string;
  /** Identifies the ASR capture generation; ended events have no input generation. */
  inputGeneration?: number;
  event: ConversationInputEvent | { type: 'ended' } | { type: 'call-record'; record: VoiceCallRecord };
};
export type VoiceConversationStart = VoiceConversationSelection & {
  callId: string;
  botId: string;
  sessionId: string;
};
export interface VoiceConversationApi {
  models(): Promise<VoiceConversationModel[]>;
  voices(selection: SpeechModelSelection): Promise<SpeechVoiceCatalog>;
  preview(input: SpeechPreviewStart): Promise<SpeechAudioResult>;
  readPreview(previewId: string): Promise<{ pcm: ArrayBuffer; done: boolean }>;
  stopPreview(previewId: string): Promise<void>;
  preference(botId: string): Promise<VoiceConversationPreference>;
  setPreference(
    botId: string,
    selection: VoiceConversationSelection | null | undefined,
    /** undefined preserves this override; null restores the current default. */
    sentencePlayback?: boolean | null,
  ): Promise<VoiceConversationPreference>;
  start(input: VoiceConversationStart): Promise<{ callId: string }>;
  /** Explicit message read-aloud: the same TTS lease and queue, without ASR or microphone input. */
  promoteTurn?(callId: string, inputId: string): Promise<boolean>;
  submitTurn?(callId: string, inputId: string, text: string, forceHandoff: boolean): Promise<boolean>;
  startPlayback(input: VoiceConversationStart): Promise<{ callId: string }>;
  /** One finalized ASR utterance, bound to the active local call; never creates a task. */
  classifyExit(
    callId: string,
    utteranceId: string,
    inputGeneration: number,
  ): Promise<VoiceExitDecision>;
  audio(input: {
    callId: string;
    pcm: ArrayBuffer;
    inputGeneration?: number;
    trace?: AudioTrace;
  }): void;
  setInputMuted(callId: string, muted: boolean): Promise<{ inputGeneration: number }>;
  finishUtterance(callId: string): Promise<void>;
  end(callId: string): Promise<void>;
  speak(input: {
    callId: string;
    requestId: string;
    text: string;
    /** Main defers unfinished replies while an outgoing reply hook is enabled. */
    streaming?: boolean;
  }): Promise<SpeechStartResult>;
  readSpeech(callId: string, requestId: string): Promise<{ pcm: ArrayBuffer; done: boolean }>;
  interrupt(callId: string): Promise<void>;
  onEvent(callback: (event: VoiceConversationEvent) => void): () => void;
}

export function normalizeVoiceConversationSelection(
  value: unknown,
): VoiceConversationSelection | undefined {
  if (!value || typeof value !== 'object') return undefined;
  const route = normalizeSpeechModelSelection(value);
  const voice = normalizeSpeechVoiceId((value as Partial<VoiceConversationSelection>).voice);
  const speed = (value as Partial<VoiceConversationSelection>).speed;
  // Check the broad protocol envelope here; Main checks the resolved adapter's
  // narrower range, never a renderer-supplied protocol for an official endpoint.
  if (speed !== undefined && (typeof speed !== 'number' || !Number.isFinite(speed) || speed < 0.25 || speed > 4))
    return undefined;
  return route && voice ? { ...route, voice, ...(speed !== undefined ? { speed } : {}) } : undefined;
}

/** Voice IDs are opaque provider identifiers; MiniMax IDs include spaces and parentheses. */
export function normalizeSpeechVoiceId(value: unknown): string | undefined {
  if (typeof value !== 'string' || value.length > 128) return undefined;
  const voice = value.trim();
  // Retain the path/control-character boundary for manual IDs. URL use also encodes the ID.
  const invalid = [...value].some(
    (char) =>
      char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127 || char === '/' || char === '\\',
  );
  return voice && !invalid ? voice : undefined;
}

export function normalizeSpeechModelSelection(value: unknown): SpeechModelSelection | undefined {
  if (!value || typeof value !== 'object') return undefined;
  const { modelId, providerId, agent, protocol } = value as Partial<SpeechModelSelection>;
  if (
    typeof modelId !== 'string' ||
    !modelId.trim() ||
    modelId.length > 256 ||
    (providerId !== undefined &&
      (typeof providerId !== 'string' || !providerId.trim() || providerId.length > 256)) ||
    (protocol !== undefined && !SPEECH_PROTOCOLS.includes(protocol)) ||
    ((providerId === undefined || providerId === 'xd') &&
      protocol !== undefined &&
      protocol !== 'openai') ||
    (agent !== undefined && !['claude-code', 'codex', 'pi'].includes(agent)) ||
    (providerId !== undefined && providerId !== 'xd' && !agent) ||
    ((providerId === undefined || providerId === 'xd') && agent !== undefined)
  )
    return undefined;
  return {
    modelId: modelId.trim(),
    ...(providerId ? { providerId } : {}),
    ...(agent ? { agent } : {}),
    ...(protocol ? { protocol } : {}),
  };
}

export function normalizeVoiceConversationPreferences(
  value: unknown,
): Record<string, VoiceConversationSelection | null> {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
  return Object.fromEntries(
    Object.entries(value).flatMap(([id, raw]) => {
      const selection = raw === null ? null : normalizeVoiceConversationSelection(raw);
      return id.trim() && id.length <= 256 && selection !== undefined ? [[id, selection]] : [];
    }),
  );
}

/** Only explicit per-companion choices are stored, never copies of the default. */
export function normalizeSentencePlaybackOverrides(value: unknown): Record<string, boolean> {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
  return Object.fromEntries(
    Object.entries(value).filter(
      ([id, enabled]) => id.trim() && id.length <= 256 && typeof enabled === 'boolean',
    ),
  ) as Record<string, boolean>;
}