@lawpath-tech/openclaw 2026.2.21-20 → 2026.2.21-22

package/extensions/voice-call/src/providers/realtime-session.ts

@@ -0,0 +1,210 @@
+/**
+ * OpenAI Realtime API session provider for voice calls.
+ *
+ * Replaces the STT → LLM → TTS chain with native speech-to-speech via the
+ * OpenAI Agents SDK RealtimeSession + TwilioRealtimeTransportLayer.
+ * Achieves ~200-500ms response latency vs 2-14s with the embedded agent.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { WebSocket as NodeWebSocket } from "ws";
+import { RealtimeAgent, RealtimeSession, tool, backgroundResult } from "@openai/agents/realtime";
+import { TwilioRealtimeTransportLayer } from "@openai/agents-extensions";
+import { z } from "zod";
+import type { VoiceCallConfig } from "../config.js";
+
+const execFileAsync = promisify(execFile);
+
+const SCRIPT_TIMEOUT_MS = 15_000;
+
+async function runScript(command: string, args: string[]): Promise<string> {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      timeout: SCRIPT_TIMEOUT_MS,
+      maxBuffer: 1024 * 512,
+      env: process.env,
+    });
+    return stdout.trim() || stderr.trim() || "(no output)";
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Error: ${msg}`;
+  }
+}
+
+function buildRealtimeTools() {
+  const stripeGross = tool({
+    name: "stripe_gross_mtd",
+    description:
+      "Get Stripe gross revenue month-to-date. Returns current MTD figures, daily average, and target tracking.",
+    parameters: z.object({}),
+    execute: async () => {
+      return backgroundResult(
+        await runScript("node", ["/root/clawd/skills/stripe/scripts/stripe.js", "gross-mtd"]),
+      );
+    },
+  });
+
+  const stripeDailySummary = tool({
+    name: "stripe_daily_summary",
+    description:
+      "Get Stripe daily summary for a specific date (charges, refunds, net). Defaults to yesterday if no date provided.",
+    parameters: z.object({
+      date: z.string().optional().describe("Date in YYYY-MM-DD format. Defaults to yesterday."),
+    }),
+    execute: async ({ date }) => {
+      const args = ["/root/clawd/skills/stripe/scripts/stripe.js", "daily-summary"];
+      if (date) args.push("--date", date);
+      return backgroundResult(await runScript("node", args));
+    },
+  });
+
+  const webSearch = tool({
+    name: "web_search",
+    description:
+      "Search the web for current information. Use for news, current events, factual lookups.",
+    parameters: z.object({
+      query: z.string().describe("Search query"),
+    }),
+    execute: async ({ query }) => {
+      return backgroundResult(
+        await runScript("node", [
+          "-e",
+          `import('undici').then(({fetch})=>fetch('https://api.search.brave.com/res/v1/web/search?q='+encodeURIComponent(${JSON.stringify(query)}),{headers:{'X-Subscription-Token':process.env.BRAVE_SEARCH_API_KEY||''}}).then(r=>r.json()).then(d=>{const results=(d.web?.results||[]).slice(0,5).map(r=>r.title+': '+r.description).join('\\n');console.log(results||'No results')})).catch(e=>console.error(e.message))`,
+        ]),
+      );
+    },
+  });
+
+  const memoryRecall = tool({
+    name: "memory_recall",
+    description:
+      "Recall stored memories and context. Use to check preferences, past decisions, or remembered facts.",
+    parameters: z.object({
+      query: z.string().describe("What to recall — topic, person name, or context"),
+    }),
+    execute: async ({ query }) => {
+      return backgroundResult(
+        await runScript("node", [
+          "/root/clawd/skills/memory/scripts/memory.js",
+          "recall",
+          "UCH9TS4TB",
+          query,
+        ]),
+      );
+    },
+  });
+
+  const uptimeCheck = tool({
+    name: "uptime_check",
+    description: "Check current uptime status of monitored services via UptimeRobot.",
+    parameters: z.object({}),
+    execute: async () => {
+      return backgroundResult(
+        await runScript("node", ["/root/clawd/skills/uptime-robot/scripts/uptime.js"]),
+      );
+    },
+  });
+
+  const shellExec = tool({
+    name: "run_command",
+    description:
+      "Execute a shell command on the server. Use for quick checks like date, uptime, disk usage, git status, etc.",
+    parameters: z.object({
+      command: z.string().describe("Shell command to run"),
+    }),
+    execute: async ({ command }) => {
+      return backgroundResult(await runScript("bash", ["-c", command]));
+    },
+  });
+
+  return [stripeGross, stripeDailySummary, webSearch, memoryRecall, uptimeCheck, shellExec];
+}
+
+export type RealtimeCallSession = {
+  session: RealtimeSession;
+  close: () => void;
+};
+
+export function createRealtimeCallSession(params: {
+  twilioWebSocket: WebSocket | NodeWebSocket;
+  voiceConfig: VoiceCallConfig;
+  callId: string;
+  from: string;
+}): RealtimeCallSession {
+  const { twilioWebSocket, voiceConfig, callId, from } = params;
+
+  const systemPrompt =
+    voiceConfig.responseSystemPrompt ??
+    `You are Clawpath — Lawpath's AI intern — on a PHONE CALL. You're Australian, warm, and casual. You naturally say things like "no worries", "reckon", "too easy", "beauty". You're a proud Rabbitohs fan.
+
+VOICE RULES (critical):
+- MAX 2 short sentences per reply. This is spoken aloud, not text.
+- NEVER use lists, bullet points, markdown, asterisks, or numbered items.
+- NEVER read out URLs or long technical details.
+- Use tools when the caller asks you to look something up, check data, or do something. Say "gimme a sec" first so they know you're working on it.
+- If the caller says bye, goodbye, or wants to end the call, say a brief farewell and include [END_CALL] at the end of your response.
+- Match the caller's energy — quick question gets a quick answer, yarn gets a yarn.`;
+
+  const agent = new RealtimeAgent({
+    name: "Clawpath",
+    instructions: `${systemPrompt}\n\nThe caller's phone number is ${from}. Call ID: ${callId}.`,
+    tools: buildRealtimeTools(),
+  });
+
+  const voice = voiceConfig.realtimeVoice || "verse";
+
+  const transport = new TwilioRealtimeTransportLayer({
+    twilioWebSocket,
+  });
+
+  const model = voiceConfig.realtimeModel || "gpt-4o-realtime-preview";
+
+  const session = new RealtimeSession(agent, {
+    transport,
+    model,
+    config: {
+      audio: {
+        output: {
+          voice,
+        },
+      },
+    },
+    tracingDisabled: true,
+  });
+
+  session.on("error", (error: unknown) => {
+    console.error(`[voice-call] [realtime] Session error for call ${callId}:`, error);
+  });
+
+  session.on("agent_updated" as any, (newAgent: unknown) => {
+    console.log(`[voice-call] [realtime] Agent updated for call ${callId}:`, newAgent);
+  });
+
+  const apiKey = voiceConfig.streaming?.openaiApiKey || process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("OpenAI API key required for realtime voice mode");
+  }
+
+  session
+    .connect({ apiKey })
+    .then(() => {
+      console.log(
+        `[voice-call] [realtime] Connected for call ${callId} (model=${model}, voice=${voice})`,
+      );
+    })
+    .catch((err) => {
+      console.error(`[voice-call] [realtime] Connection failed for call ${callId}:`, err);
+    });
+
+  return {
+    session,
+    close: () => {
+      try {
+        session.close();
+      } catch {
+        // best effort
+      }
+    },
+  };
+}

package/extensions/voice-call/src/webhook.ts

@@ -6,6 +6,8 @@ import {
   readRequestBodyWithLimit,
   requestBodyErrorToText,
 } from "openclaw/plugin-sdk";
+import type { WebSocket as NodeWebSocket } from "ws";
+import { WebSocketServer } from "ws";
 import type { VoiceCallConfig } from "./config.js";
 import type { CoreConfig } from "./core-bridge.js";
 import type { CallManager } from "./manager.js";
@@ -30,9 +32,18 @@ export class VoiceCallWebhookServer {
   private coreConfig: CoreConfig | null;
   private staleCallReaperInterval: ReturnType<typeof setInterval> | null = null;
 
-  /** Media stream handler for bidirectional audio (when streaming enabled) */
+  /** Media stream handler for bidirectional audio (when streaming enabled, embedded mode) */
   private mediaStreamHandler: MediaStreamHandler | null = null;
 
+  /** Whether we're using the Realtime API for speech-to-speech (bypasses STT/TTS chain) */
+  private isRealtimeMode = false;
+
+  /** Realtime WebSocket server for direct Twilio → OpenAI Realtime API bridging */
+  private realtimeWss: WebSocketServer | null = null;
+
+  /** Active realtime sessions keyed by call SID */
+  private realtimeSessions = new Map<string, { session: unknown; close: () => void }>();
+
   constructor(
     config: VoiceCallConfig,
     manager: CallManager,
@@ -43,10 +54,14 @@ export class VoiceCallWebhookServer {
     this.manager = manager;
     this.provider = provider;
     this.coreConfig = coreConfig ?? null;
+    this.isRealtimeMode = config.responseMode === "realtime";
 
-    // Initialize media stream handler if streaming is enabled
     if (config.streaming?.enabled) {
-      this.initializeMediaStreaming();
+      if (this.isRealtimeMode) {
+        this.initializeRealtimeStreaming();
+      } else {
+        this.initializeMediaStreaming();
+      }
     }
   }
 
@@ -57,6 +72,124 @@ export class VoiceCallWebhookServer {
     return this.mediaStreamHandler;
   }
 
+  /**
+   * Initialize realtime streaming mode.
+   * In this mode, each Twilio WebSocket connection is bridged directly to the
+   * OpenAI Realtime API via TwilioRealtimeTransportLayer for speech-to-speech.
+   */
+  private initializeRealtimeStreaming(): void {
+    const apiKey = this.config.streaming?.openaiApiKey || process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      console.warn("[voice-call] Realtime mode enabled but no OpenAI API key found");
+      return;
+    }
+    console.log("[voice-call] Realtime speech-to-speech mode initialized");
+  }
+
+  /**
+   * Handle WebSocket upgrade for realtime mode.
+   * Creates a RealtimeCallSession that bridges Twilio <-> OpenAI Realtime API.
+   */
+  private handleRealtimeUpgrade(
+    request: http.IncomingMessage,
+    socket: import("node:stream").Duplex,
+    head: Buffer,
+  ): void {
+    if (!this.realtimeWss) {
+      this.realtimeWss = new WebSocketServer({ noServer: true });
+      this.realtimeWss.on("connection", (ws, req) => {
+        this.handleRealtimeConnection(ws as unknown as NodeWebSocket, req);
+      });
+    }
+    this.realtimeWss.handleUpgrade(request, socket, head, (ws) => {
+      this.realtimeWss?.emit("connection", ws, request);
+    });
+  }
+
+  /**
+   * Handle a new Twilio WebSocket connection in realtime mode.
+   * Waits for the Twilio "start" message to get the callSid, then creates
+   * a RealtimeCallSession that bridges directly to the OpenAI Realtime API.
+   */
+  private handleRealtimeConnection(ws: NodeWebSocket, _request: http.IncomingMessage): void {
+    let callSid: string | null = null;
+    let sessionCreated = false;
+
+    ws.on("message", (data: Buffer) => {
+      try {
+        const message = JSON.parse(data.toString());
+
+        if (message.event === "start" && !sessionCreated) {
+          callSid = message.start?.callSid || null;
+          if (!callSid) {
+            console.warn("[voice-call] [realtime] Missing callSid in start message");
+            ws.close(1008, "Missing callSid");
+            return;
+          }
+
+          const call = this.manager.getCallByProviderCallId(callSid);
+          const from = call?.from || message.start?.customParameters?.from || "unknown";
+
+          if (this.provider.name === "twilio") {
+            const twilio = this.provider as TwilioProvider;
+            const token = message.start?.customParameters?.token;
+            if (!twilio.isValidStreamToken(callSid, token)) {
+              console.warn(`[voice-call] [realtime] Invalid stream token for ${callSid}`);
+              ws.close(1008, "Unauthorized");
+              return;
+            }
+            const streamSid = message.streamSid || "";
+            twilio.registerCallStream(callSid, streamSid);
+          }
+
+          console.log(`[voice-call] [realtime] Creating session for call ${callSid} from ${from}`);
+          sessionCreated = true;
+
+          import("./providers/realtime-session.js")
+            .then(({ createRealtimeCallSession }) => {
+              const realtimeSession = createRealtimeCallSession({
+                twilioWebSocket: ws,
+                voiceConfig: this.config,
+                callId: call?.callId || callSid!,
+                from,
+              });
+              this.realtimeSessions.set(callSid!, realtimeSession);
+            })
+            .catch((err) => {
+              console.error(`[voice-call] [realtime] Failed to create session:`, err);
+              ws.close(1011, "Session creation failed");
+            });
+        }
+      } catch (err) {
+        // Non-JSON messages are normal (binary audio frames in some edge cases)
+      }
+    });
+
+    ws.on("close", () => {
+      if (callSid) {
+        console.log(`[voice-call] [realtime] WebSocket closed for call ${callSid}`);
+        const session = this.realtimeSessions.get(callSid);
+        if (session) {
+          session.close();
+          this.realtimeSessions.delete(callSid);
+        }
+        if (this.provider.name === "twilio") {
+          (this.provider as TwilioProvider).unregisterCallStream(callSid);
+        }
+        const call = this.manager.getCallByProviderCallId(callSid);
+        if (call) {
+          void this.manager.endCall(call.callId).catch((err) => {
+            console.warn(`[voice-call] [realtime] Failed to end call ${call.callId}:`, err);
+          });
+        }
+      }
+    });
+
+    ws.on("error", (error) => {
+      console.error("[voice-call] [realtime] WebSocket error:", error);
+    });
+  }
+
   /**
    * Initialize media streaming with OpenAI Realtime STT.
    */
@@ -190,13 +323,18 @@ export class VoiceCallWebhookServer {
       });
 
       // Handle WebSocket upgrades for media streams
-      if (this.mediaStreamHandler) {
+      if (this.isRealtimeMode || this.mediaStreamHandler) {
         this.server.on("upgrade", (request, socket, head) => {
           const url = new URL(request.url || "/", `http://${request.headers.host}`);
 
           if (url.pathname === streamPath) {
-            console.log("[voice-call] WebSocket upgrade for media stream");
-            this.mediaStreamHandler?.handleUpgrade(request, socket, head);
+            if (this.isRealtimeMode) {
+              console.log("[voice-call] WebSocket upgrade for realtime session");
+              this.handleRealtimeUpgrade(request, socket, head);
+            } else {
+              console.log("[voice-call] WebSocket upgrade for media stream");
+              this.mediaStreamHandler?.handleUpgrade(request, socket, head);
+            }
           } else {
             socket.destroy();
           }
@@ -208,7 +346,11 @@ export class VoiceCallWebhookServer {
       this.server.listen(port, bind, () => {
         const url = `http://${bind}:${port}${webhookPath}`;
         console.log(`[voice-call] Webhook server listening on ${url}`);
-        if (this.mediaStreamHandler) {
+        if (this.isRealtimeMode) {
+          console.log(
+            `[voice-call] Realtime speech-to-speech WebSocket on ws://${bind}:${port}${streamPath}`,
+          );
+        } else if (this.mediaStreamHandler) {
           console.log(`[voice-call] Media stream WebSocket on ws://${bind}:${port}${streamPath}`);
         }
         resolve(url);
@@ -257,6 +399,10 @@ export class VoiceCallWebhookServer {
       clearInterval(this.staleCallReaperInterval);
       this.staleCallReaperInterval = null;
     }
+    for (const session of this.realtimeSessions.values()) {
+      session.close();
+    }
+    this.realtimeSessions.clear();
     return new Promise((resolve) => {
       if (this.server) {
         this.server.close(() => {
@@ -365,14 +511,26 @@ export class VoiceCallWebhookServer {
     return readRequestBodyWithLimit(req, { maxBytes, timeoutMs });
   }
 
+  private static readonly TOOL_HINT_PATTERNS = [
+    /\b(stripe|revenue|charges|gross|mtd|sales|refund|subscription)\b/i,
+    /\b(check|look up|pull|get|show|what(?:'s| is| are| was| were))\b.*\b(number|metric|data|status|uptime|error|log)\b/i,
+    /\b(yesterday|today|this week|this month|last month)\b.*\b(performance|revenue|gross|net)\b/i,
+    /\b(search|google|find out|look into|news|happening|weather)\b/i,
+  ];
+
+  private looksLikeToolQuery(message: string): boolean {
+    return VoiceCallWebhookServer.TOOL_HINT_PATTERNS.some((p) => p.test(message));
+  }
+
   /**
    * Handle auto-response for inbound calls using the agent system.
    * Supports tool calling for richer voice interactions.
+   * When a tool-heavy query is detected, speaks filler audio immediately
+   * so the caller knows we're working on it.
    */
   private async handleInboundResponse(callId: string, userMessage: string): Promise<void> {
     console.log(`[voice-call] Auto-responding to inbound call ${callId}: "${userMessage}"`);
 
-    // Get call context for conversation history
     const call = this.manager.getCall(callId);
     if (!call) {
       console.warn(`[voice-call] Call ${callId} not found for auto-response`);
@@ -384,6 +542,12 @@ export class VoiceCallWebhookServer {
       return;
     }
 
+    // Speak filler audio immediately for queries that likely need tools,
+    // so the caller doesn't wait in silence while scripts run.
+    if (this.looksLikeToolQuery(userMessage)) {
+      this.manager.speak(callId, "Gimme a sec, let me check that for ya.").catch(() => {});
+    }
+
     try {
       const { generateVoiceResponse } = await import("./response-generator.js");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawpath-tech/openclaw",
-  "version": "2026.2.21-20",
+  "version": "2026.2.21-22",
   "description": "Multi-channel AI gateway with extensible messaging integrations",
   "keywords": [],
   "homepage": "https://github.com/openclaw/openclaw#readme",
@@ -154,6 +154,8 @@
     "@mariozechner/pi-coding-agent": "0.63.1",
     "@mariozechner/pi-tui": "0.63.1",
     "@mozilla/readability": "^0.6.0",
+    "@openai/agents": "^0.8.1",
+    "@openai/agents-extensions": "^0.8.1",
     "@sinclair/typebox": "0.34.48",
     "@slack/bolt": "^4.6.0",
     "@slack/web-api": "^7.14.1",

package/dist/plugin-sdk/web-DBo-6RyH.js

@@ -1,65 +0,0 @@
-import { a as WA_WEB_AUTH_DIR, g as webAuthExists, s as logWebSelfId, u as pickWebChannel } from "./accounts-Ciwy7Yxd.js";
-import "./reply-DEepmBkT.js";
-import "./paths-DVWx7USN.js";
-import "./github-copilot-token-Cg0YPPSu.js";
-import "./plugins-DIzw7Ncy.js";
-import "./fetch-b2Zm8y7X.js";
-import "./registry-O1yza0Vh.js";
-import "./retry-JFNwfUew.js";
-import "./send-DEV4iiFj.js";
-import "./config-9OZuRn0C.js";
-import "./subsystem-C4Rh0kdL.js";
-import "./command-format-DcBXOX9Z.js";
-import "./model-selection-CXooYLb2.js";
-import "./agent-scope-cT7IxdHY.js";
-import "./manifest-registry-sgHvjA6E.js";
-import "./redact-DPnDWsnT.js";
-import "./errors-Bv8oZiTO.js";
-import "./channel-activity-CCnr-9bS.js";
-import "./image-ops-B8aJIly2.js";
-import "./ssrf-DKZ8eBrk.js";
-import "./local-roots-D4PCK2jj.js";
-import "./ir-CD5VqKGg.js";
-import "./chunk-DyzO7IVo.js";
-import "./message-channel-DmB4bGFh.js";
-import "./bindings-CKqdifyU.js";
-import "./markdown-tables-Bo-r4msS.js";
-import "./render-BiJZ5W4Z.js";
-import "./tables-C_81Ve2l.js";
-import "./send-D1C2sJG1.js";
-import "./tool-images-BvjD_HnR.js";
-import "./target-errors-C638yp2-.js";
-import "./send-CK3DCPv-.js";
-import "./send-D-spKwjf.js";
-import "./runner-DztRiWhh.js";
-import "./reply-prefix-BF0omhZE.js";
-import "./tokens-K9ITCatc.js";
-import "./skill-commands-Dv5AeOZQ.js";
-import "./skills-5hEda4_Y.js";
-import "./chrome-BO7SUTgY.js";
-import "./thinking-DexKPSsI.js";
-import "./accounts-wSu5JyDM.js";
-import "./accounts-DUBJHEgi.js";
-import "./deliver-BO_wt0wd.js";
-import "./pi-embedded-helpers-DU0nLxRU.js";
-import "./paths-BNQjLbn7.js";
-import "./diagnostic-DKyVS3IK.js";
-import "./store-DoRXD0QB.js";
-import { n as monitorWebInbox, t as monitorWebChannel } from "./channel-web-BHNS_E7F.js";
-import "./image-C31B_R8P.js";
-import "./pi-model-discovery-LbcEa65a.js";
-import "./api-key-rotation-ElOMCP9r.js";
-import "./sqlite-DUu0dwic.js";
-import "./diagnostic-session-state-Wd5tNeQG.js";
-import "./manager-CZPPxI6R.js";
-import "./commands-registry-BsSKPwgj.js";
-import "./send-DrYvH25B.js";
-import "./proxy-MquBDehr.js";
-import "./resolve-route-B63ztF-V.js";
-import "./replies-Bnu7HnvW.js";
-import "./outbound-attachment-CCxMtk8m.js";
-import { n as sendMessageWhatsApp } from "./outbound-dAcQHyyr.js";
-import { i as waitForWaConnection, t as createWaSocket } from "./session-DRJl5tKC.js";
-import { t as loginWeb } from "./login-CW17h3xU.js";
-
-export { WA_WEB_AUTH_DIR, createWaSocket, logWebSelfId, loginWeb, monitorWebChannel, monitorWebInbox, pickWebChannel, sendMessageWhatsApp, waitForWaConnection, webAuthExists };