@openclaw/voice-call 2026.5.2 → 2026.5.3-beta.1

package/src/providers/twilio.types.ts

@@ -1,17 +0,0 @@
-import type { WebhookSecurityConfig } from "../config.js";
-
-/**
- * Twilio Voice API provider options.
- */
-export interface TwilioProviderOptions {
-  /** Allow ngrok free tier compatibility mode (loopback only, less secure) */
-  allowNgrokFreeTierLoopbackBypass?: boolean;
-  /** Override public URL for signature verification */
-  publicUrl?: string;
-  /** Path for media stream WebSocket (e.g., /voice/stream) */
-  streamPath?: string;
-  /** Skip webhook signature verification (development only) */
-  skipVerification?: boolean;
-  /** Webhook security options (forwarded headers/allowlist) */
-  webhookSecurity?: WebhookSecurityConfig;
-}

package/src/realtime-defaults.ts

@@ -1,3 +0,0 @@
-import { REALTIME_VOICE_AGENT_CONSULT_TOOL_NAME } from "openclaw/plugin-sdk/realtime-voice";
-
-export const DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS = `You are OpenClaw's phone-call realtime voice interface. Keep spoken replies brief and natural. When a question needs deeper reasoning, current information, or tools, call ${REALTIME_VOICE_AGENT_CONSULT_TOOL_NAME} before answering.`;

package/src/realtime-fast-context.test.ts

@@ -1,88 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { VoiceCallRealtimeFastContextConfig } from "./config.js";
-
-const mocks = vi.hoisted(() => ({
-  getActiveMemorySearchManager: vi.fn(),
-}));
-
-vi.mock("openclaw/plugin-sdk/memory-host-search", () => ({
-  getActiveMemorySearchManager: mocks.getActiveMemorySearchManager,
-}));
-
-import { resolveRealtimeFastContextConsult } from "./realtime-fast-context.js";
-
-const cfg = {} as OpenClawConfig;
-
-function createFastContextConfig(
-  overrides: Partial<VoiceCallRealtimeFastContextConfig> = {},
-): VoiceCallRealtimeFastContextConfig {
-  return {
-    enabled: true,
-    timeoutMs: 800,
-    maxResults: 3,
-    sources: ["memory", "sessions"],
-    fallbackToConsult: false,
-    ...overrides,
-  };
-}
-
-function createLogger() {
-  return {
-    debug: vi.fn(),
-    warn: vi.fn(),
-  };
-}
-
-describe("resolveRealtimeFastContextConsult", () => {
-  beforeEach(() => {
-    mocks.getActiveMemorySearchManager.mockReset();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("falls back to the full consult when memory manager setup fails", async () => {
-    const logger = createLogger();
-    mocks.getActiveMemorySearchManager.mockRejectedValue(new Error("memory misconfigured"));
-
-    await expect(
-      resolveRealtimeFastContextConsult({
-        cfg,
-        agentId: "main",
-        sessionKey: "voice:15550001234",
-        config: createFastContextConfig({ fallbackToConsult: true }),
-        args: { question: "What do you remember?" },
-        logger,
-      }),
-    ).resolves.toEqual({ handled: false });
-
-    expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining("memory misconfigured"));
-  });
-
-  it("returns a bounded miss when memory manager setup exceeds the fast context timeout", async () => {
-    vi.useFakeTimers();
-    const logger = createLogger();
-    mocks.getActiveMemorySearchManager.mockReturnValue(new Promise(() => {}));
-
-    const resultPromise = resolveRealtimeFastContextConsult({
-      cfg,
-      agentId: "main",
-      sessionKey: "voice:15550001234",
-      config: createFastContextConfig({ fallbackToConsult: false, timeoutMs: 25 }),
-      args: { question: "What do you remember?" },
-      logger,
-    });
-
-    await vi.advanceTimersByTimeAsync(25);
-
-    await expect(resultPromise).resolves.toEqual({
-      handled: true,
-      result: {
-        text: expect.stringContaining("No relevant OpenClaw memory or session context"),
-      },
-    });
-    expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining("timed out after 25ms"));
-  });
-});

package/src/realtime-fast-context.ts

@@ -1,165 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
-import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
-import { getActiveMemorySearchManager } from "openclaw/plugin-sdk/memory-host-search";
-import {
-  parseRealtimeVoiceAgentConsultArgs,
-  type RealtimeVoiceAgentConsultResult,
-} from "openclaw/plugin-sdk/realtime-voice";
-import type { VoiceCallRealtimeFastContextConfig } from "./config.js";
-
-type Logger = {
-  debug?: (message: string) => void;
-  warn: (message: string) => void;
-};
-
-type MemorySearchHit = {
-  path: string;
-  startLine: number;
-  endLine: number;
-  snippet: string;
-  source: "memory" | "sessions";
-  score: number;
-};
-
-type FastContextLookupResult =
-  | { status: "unavailable"; error?: string }
-  | { status: "hits"; hits: MemorySearchHit[] };
-
-type RealtimeFastContextConsultResult =
-  | { handled: false }
-  | { handled: true; result: RealtimeVoiceAgentConsultResult };
-
-const MAX_SNIPPET_CHARS = 700;
-
-class RealtimeFastContextTimeoutError extends Error {
-  constructor(timeoutMs: number) {
-    super(`fast context lookup timed out after ${timeoutMs}ms`);
-    this.name = "RealtimeFastContextTimeoutError";
-  }
-}
-
-function normalizeSnippet(text: string): string {
-  const normalized = text.replace(/\s+/g, " ").trim();
-  if (normalized.length <= MAX_SNIPPET_CHARS) {
-    return normalized;
-  }
-  return `${normalized.slice(0, MAX_SNIPPET_CHARS - 1).trimEnd()}...`;
-}
-
-function buildSearchQuery(args: unknown): string {
-  const parsed = parseRealtimeVoiceAgentConsultArgs(args);
-  return [parsed.question, parsed.context].filter(Boolean).join("\n\n");
-}
-
-function buildContextText(params: { query: string; hits: MemorySearchHit[] }): string {
-  const hits = params.hits
-    .map((hit, index) => {
-      const location = `${hit.path}:${hit.startLine}-${hit.endLine}`;
-      return `${index + 1}. [${hit.source}] ${location}\n${normalizeSnippet(hit.snippet)}`;
-    })
-    .join("\n\n");
-  return [
-    "Fast OpenClaw memory context found for the live caller.",
-    "Use this context only if it answers the caller's question. If it is not relevant, say briefly that you do not have that context handy.",
-    `Question:\n${params.query}`,
-    `Context:\n${hits}`,
-  ].join("\n\n");
-}
-
-function buildMissText(query: string): string {
-  return [
-    "No relevant OpenClaw memory or session context was found quickly for the live caller.",
-    "Answer briefly that you do not have that context handy. Do not keep checking unless the caller asks you to.",
-    `Question:\n${query}`,
-  ].join("\n\n");
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<T>((_resolve, reject) => {
-        timer = setTimeout(() => reject(new RealtimeFastContextTimeoutError(timeoutMs)), timeoutMs);
-      }),
-    ]);
-  } finally {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  }
-}
-
-async function lookupFastContext(params: {
-  cfg: OpenClawConfig;
-  agentId: string;
-  sessionKey: string;
-  config: VoiceCallRealtimeFastContextConfig;
-  query: string;
-}): Promise<FastContextLookupResult> {
-  const memory = await getActiveMemorySearchManager({
-    cfg: params.cfg,
-    agentId: params.agentId,
-  });
-  if (!memory.manager) {
-    return {
-      status: "unavailable",
-      error: memory.error ?? "no active memory manager",
-    };
-  }
-  const hits = await memory.manager.search(params.query, {
-    maxResults: params.config.maxResults,
-    sessionKey: params.sessionKey,
-    sources: params.config.sources,
-  });
-  return { status: "hits", hits };
-}
-
-export async function resolveRealtimeFastContextConsult(params: {
-  cfg: OpenClawConfig;
-  agentId: string;
-  sessionKey: string;
-  config: VoiceCallRealtimeFastContextConfig;
-  args: unknown;
-  logger: Logger;
-}): Promise<RealtimeFastContextConsultResult> {
-  if (!params.config.enabled) {
-    return { handled: false };
-  }
-
-  const query = buildSearchQuery(params.args);
-  try {
-    const lookup = await withTimeout(
-      lookupFastContext({
-        cfg: params.cfg,
-        agentId: params.agentId,
-        sessionKey: params.sessionKey,
-        config: params.config,
-        query,
-      }),
-      params.config.timeoutMs,
-    );
-    if (lookup.status === "unavailable") {
-      params.logger.debug?.(`[voice-call] realtime fast context unavailable: ${lookup.error}`);
-      return params.config.fallbackToConsult
-        ? { handled: false }
-        : { handled: true, result: { text: buildMissText(query) } };
-    }
-    const { hits } = lookup;
-    if (hits.length === 0) {
-      return params.config.fallbackToConsult
-        ? { handled: false }
-        : { handled: true, result: { text: buildMissText(query) } };
-    }
-    return {
-      handled: true,
-      result: { text: buildContextText({ query, hits }) },
-    };
-  } catch (error) {
-    const message = formatErrorMessage(error);
-    params.logger.debug?.(`[voice-call] realtime fast context lookup failed: ${message}`);
-    return params.config.fallbackToConsult
-      ? { handled: false }
-      : { handled: true, result: { text: buildMissText(query) } };
-  }
-}

package/src/realtime-transcription.runtime.ts

@@ -1,4 +0,0 @@
-export {
-  getRealtimeTranscriptionProvider,
-  listRealtimeTranscriptionProviders,
-} from "openclaw/plugin-sdk/realtime-transcription";

package/src/realtime-voice.runtime.ts

@@ -1,5 +0,0 @@
-export {
-  getRealtimeVoiceProvider,
-  listRealtimeVoiceProviders,
-  resolveConfiguredRealtimeVoiceProvider,
-} from "openclaw/plugin-sdk/realtime-voice";

package/src/response-generator.test.ts

@@ -1,321 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { VoiceCallConfigSchema } from "./config.js";
-import type { CoreAgentDeps, CoreConfig } from "./core-bridge.js";
-import { generateVoiceResponse } from "./response-generator.js";
-
-function createAgentRuntime(payloads: Array<Record<string, unknown>>) {
-  const sessionStore: Record<string, { sessionId: string; updatedAt: number }> = {};
-  const saveSessionStore = vi.fn(async () => {});
-  const updateSessionStore = vi.fn(
-    async (
-      _storePath: string,
-      mutator: (store: Record<string, { sessionId: string; updatedAt: number }>) => unknown,
-    ) => {
-      return await mutator(sessionStore);
-    },
-  );
-  const runEmbeddedPiAgent = vi.fn(async () => ({
-    payloads,
-    meta: { durationMs: 12, aborted: false },
-  }));
-  const resolveAgentDir = vi.fn((_cfg: CoreConfig, agentId: string) => {
-    return `/tmp/openclaw/agents/${agentId}`;
-  });
-  const resolveAgentWorkspaceDir = vi.fn((_cfg: CoreConfig, agentId: string) => {
-    return `/tmp/openclaw/workspace/${agentId}`;
-  });
-  const resolveAgentIdentity = vi.fn((_cfg: CoreConfig, agentId: string) => ({
-    name: `${agentId} tester`,
-  }));
-  const resolveStorePath = vi.fn((_store: string | undefined, params: { agentId?: string }) => {
-    return `/tmp/openclaw/${params.agentId ?? "main"}/sessions.json`;
-  });
-  const resolveSessionFilePath = vi.fn(
-    (_sessionId: string, _entry: unknown, params: { agentId?: string }) => {
-      return `/tmp/openclaw/${params.agentId ?? "main"}/sessions/session.jsonl`;
-    },
-  );
-
-  const runtime = {
-    defaults: {
-      provider: "together",
-      model: "Qwen/Qwen2.5-7B-Instruct-Turbo",
-    },
-    resolveAgentDir,
-    resolveAgentWorkspaceDir,
-    resolveAgentIdentity,
-    resolveThinkingDefault: () => "off",
-    resolveAgentTimeoutMs: () => 30_000,
-    ensureAgentWorkspace: async () => {},
-    runEmbeddedPiAgent,
-    session: {
-      resolveStorePath,
-      loadSessionStore: () => sessionStore,
-      saveSessionStore,
-      updateSessionStore,
-      resolveSessionFilePath,
-    },
-  } as unknown as CoreAgentDeps;
-
-  return {
-    runtime,
-    runEmbeddedPiAgent,
-    saveSessionStore,
-    updateSessionStore,
-    sessionStore,
-    resolveAgentDir,
-    resolveAgentWorkspaceDir,
-    resolveAgentIdentity,
-    resolveStorePath,
-    resolveSessionFilePath,
-  };
-}
-
-function requireEmbeddedAgentArgs(runEmbeddedPiAgent: ReturnType<typeof vi.fn>) {
-  const calls = runEmbeddedPiAgent.mock.calls as unknown[][];
-  const firstCall = calls[0];
-  if (!firstCall) {
-    throw new Error("voice response generator did not invoke the embedded agent");
-  }
-  const args = firstCall[0] as
-    | {
-        extraSystemPrompt?: string;
-        provider?: string;
-        model?: string;
-      }
-    | undefined;
-  if (!args?.extraSystemPrompt) {
-    throw new Error("voice response generator did not pass the spoken-output contract prompt");
-  }
-  return args;
-}
-
-async function runGenerateVoiceResponse(
-  payloads: Array<Record<string, unknown>>,
-  overrides?: {
-    runtime?: CoreAgentDeps;
-    transcript?: Array<{ speaker: "user" | "bot"; text: string }>;
-  },
-) {
-  const voiceConfig = VoiceCallConfigSchema.parse({
-    responseTimeoutMs: 5000,
-  });
-  const coreConfig = {} as CoreConfig;
-  const runtime = overrides?.runtime ?? createAgentRuntime(payloads).runtime;
-
-  const result = await generateVoiceResponse({
-    voiceConfig,
-    coreConfig,
-    agentRuntime: runtime,
-    callId: "call-123",
-    from: "+15550001111",
-    transcript: overrides?.transcript ?? [{ speaker: "user", text: "hello there" }],
-    userMessage: "hello there",
-  });
-
-  return { result };
-}
-
-describe("generateVoiceResponse", () => {
-  it("suppresses reasoning payloads and reads structured spoken output", async () => {
-    const { runtime, runEmbeddedPiAgent } = createAgentRuntime([
-      { text: "Reasoning: hidden", isReasoning: true },
-      { text: '{"spoken":"Hello from JSON."}' },
-    ]);
-    const { result } = await runGenerateVoiceResponse([], { runtime });
-
-    expect(result.text).toBe("Hello from JSON.");
-    expect(runEmbeddedPiAgent).toHaveBeenCalledTimes(1);
-    const args = requireEmbeddedAgentArgs(runEmbeddedPiAgent);
-    expect(args.extraSystemPrompt).toContain('{"spoken":"..."}');
-    expect(args.provider).toBe("together");
-    expect(args.model).toBe("Qwen/Qwen2.5-7B-Instruct-Turbo");
-  });
-
-  it("extracts spoken text from fenced JSON", async () => {
-    const { result } = await runGenerateVoiceResponse([
-      { text: '```json\n{"spoken":"Fenced JSON works."}\n```' },
-    ]);
-
-    expect(result.text).toBe("Fenced JSON works.");
-  });
-
-  it("returns silence for an explicit empty spoken contract response", async () => {
-    const { result } = await runGenerateVoiceResponse([{ text: '{"spoken":""}' }]);
-
-    expect(result.text).toBeNull();
-  });
-
-  it("strips leading planning text when model returns plain text", async () => {
-    const { result } = await runGenerateVoiceResponse([
-      {
-        text:
-          "The user responded with short text. I should keep the response concise.\n\n" +
-          "Sounds good. I can help with the next step whenever you are ready.",
-      },
-    ]);
-
-    expect(result.text).toBe("Sounds good. I can help with the next step whenever you are ready.");
-  });
-
-  it("keeps plain conversational output when no JSON contract is followed", async () => {
-    const { result } = await runGenerateVoiceResponse([
-      { text: "Absolutely. Tell me what you want to do next." },
-    ]);
-
-    expect(result.text).toBe("Absolutely. Tell me what you want to do next.");
-  });
-
-  it("pins the voice session to responseModel before running the embedded agent", async () => {
-    const { runtime, runEmbeddedPiAgent, updateSessionStore, sessionStore } = createAgentRuntime([
-      { text: '{"spoken":"Pinned model works."}' },
-    ]);
-    const voiceConfig = VoiceCallConfigSchema.parse({
-      responseModel: "openai/gpt-4.1-nano",
-      responseTimeoutMs: 5000,
-    });
-
-    const result = await generateVoiceResponse({
-      voiceConfig,
-      coreConfig: {} as CoreConfig,
-      agentRuntime: runtime,
-      callId: "call-123",
-      from: "+15550001111",
-      transcript: [{ speaker: "user", text: "hello there" }],
-      userMessage: "hello there",
-    });
-
-    expect(result.text).toBe("Pinned model works.");
-    expect(sessionStore["voice:15550001111"]).toMatchObject({
-      providerOverride: "openai",
-      modelOverride: "gpt-4.1-nano",
-      modelOverrideSource: "auto",
-    });
-    expect(updateSessionStore).toHaveBeenCalledWith(
-      "/tmp/openclaw/main/sessions.json",
-      expect.any(Function),
-    );
-    expect(runEmbeddedPiAgent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        provider: "openai",
-        model: "gpt-4.1-nano",
-        sessionKey: "voice:15550001111",
-      }),
-    );
-  });
-
-  it("uses the persisted per-call session key for classic responses", async () => {
-    const { runtime, runEmbeddedPiAgent, sessionStore } = createAgentRuntime([
-      { text: '{"spoken":"Fresh call context."}' },
-    ]);
-    const voiceConfig = VoiceCallConfigSchema.parse({
-      sessionScope: "per-call",
-      responseTimeoutMs: 5000,
-    });
-
-    const result = await generateVoiceResponse({
-      voiceConfig,
-      coreConfig: {} as CoreConfig,
-      agentRuntime: runtime,
-      callId: "call-123",
-      sessionKey: "voice:call:call-123",
-      from: "+15550001111",
-      transcript: [{ speaker: "user", text: "hello there" }],
-      userMessage: "hello there",
-    });
-
-    expect(result.text).toBe("Fresh call context.");
-    expect(sessionStore["voice:call:call-123"]).toBeDefined();
-    expect(sessionStore["voice:15550001111"]).toBeUndefined();
-    expect(runEmbeddedPiAgent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        sessionKey: "voice:call:call-123",
-        sandboxSessionKey: "agent:main:voice:call:call-123",
-      }),
-    );
-  });
-
-  it("uses the main agent workspace when voice config omits agentId", async () => {
-    const {
-      runtime,
-      runEmbeddedPiAgent,
-      resolveAgentDir,
-      resolveAgentWorkspaceDir,
-      resolveAgentIdentity,
-      resolveStorePath,
-      resolveSessionFilePath,
-    } = createAgentRuntime([{ text: '{"spoken":"Default agent."}' }]);
-    const coreConfig = {} as CoreConfig;
-
-    await generateVoiceResponse({
-      voiceConfig: VoiceCallConfigSchema.parse({ responseTimeoutMs: 5000 }),
-      coreConfig,
-      agentRuntime: runtime,
-      callId: "call-123",
-      from: "+15550001111",
-      transcript: [],
-      userMessage: "hello there",
-    });
-
-    expect(resolveStorePath).toHaveBeenCalledWith(undefined, { agentId: "main" });
-    expect(resolveAgentDir).toHaveBeenCalledWith(coreConfig, "main");
-    expect(resolveAgentWorkspaceDir).toHaveBeenCalledWith(coreConfig, "main");
-    expect(resolveAgentIdentity).toHaveBeenCalledWith(coreConfig, "main");
-    expect(resolveSessionFilePath).toHaveBeenCalledWith(expect.any(String), expect.any(Object), {
-      agentId: "main",
-    });
-    expect(runEmbeddedPiAgent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        agentDir: "/tmp/openclaw/agents/main",
-        agentId: "main",
-        sandboxSessionKey: "agent:main:voice:15550001111",
-        workspaceDir: "/tmp/openclaw/workspace/main",
-        sessionFile: "/tmp/openclaw/main/sessions/session.jsonl",
-      }),
-    );
-  });
-
-  it("uses the configured voice response agent workspace", async () => {
-    const {
-      runtime,
-      runEmbeddedPiAgent,
-      resolveAgentDir,
-      resolveAgentWorkspaceDir,
-      resolveAgentIdentity,
-      resolveStorePath,
-      resolveSessionFilePath,
-    } = createAgentRuntime([{ text: '{"spoken":"Voice agent."}' }]);
-    const coreConfig = {} as CoreConfig;
-
-    const result = await generateVoiceResponse({
-      voiceConfig: VoiceCallConfigSchema.parse({
-        agentId: "voice",
-        responseTimeoutMs: 5000,
-      }),
-      coreConfig,
-      agentRuntime: runtime,
-      callId: "call-123",
-      from: "+15550001111",
-      transcript: [],
-      userMessage: "hello there",
-    });
-
-    expect(result.text).toBe("Voice agent.");
-    expect(resolveStorePath).toHaveBeenCalledWith(undefined, { agentId: "voice" });
-    expect(resolveAgentDir).toHaveBeenCalledWith(coreConfig, "voice");
-    expect(resolveAgentWorkspaceDir).toHaveBeenCalledWith(coreConfig, "voice");
-    expect(resolveAgentIdentity).toHaveBeenCalledWith(coreConfig, "voice");
-    expect(resolveSessionFilePath).toHaveBeenCalledWith(expect.any(String), expect.any(Object), {
-      agentId: "voice",
-    });
-    expect(runEmbeddedPiAgent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        agentDir: "/tmp/openclaw/agents/voice",
-        agentId: "voice",
-        sandboxSessionKey: "agent:voice:voice:15550001111",
-        workspaceDir: "/tmp/openclaw/workspace/voice",
-        sessionFile: "/tmp/openclaw/voice/sessions/session.jsonl",
-      }),
-    );
-  });
-});