fix(voice-call): emit canonical session keys

TurboTheTurtle · TurboTheTurtle · commit a2245ed65e60 · 2026-05-19T08:13:08.000-07:00
diff --git a/docs/plugins/voice-call.md b/docs/plugins/voice-call.md
@@ -211,6 +211,11 @@ each carrier call should start with fresh context, for example reception,
 booking, IVR, or Google Meet bridge flows where the same phone number may
 represent different meetings.
 
+Generated session keys are scoped under the configured voice agent, for example
+`agent:main:voice:15550001234` for per-phone sessions or
+`agent:main:voice:call:<call-id>` for per-call sessions. Explicit session keys
+provided by an inbound route or outbound call request are preserved as-is.
+
 ## Realtime voice conversations
 
 `realtime` selects a full-duplex realtime voice provider for live call
@@ -233,7 +238,7 @@ Current runtime behaviour:
 - `realtime.agentContext.enabled` is default-off. When enabled, Voice Call injects a bounded agent identity, system prompt override, and selected workspace-file capsule into the realtime provider instructions at session setup.
 - `realtime.fastContext.enabled` is default-off. When enabled, Voice Call first searches indexed memory/session context for the consult question and returns those snippets to the realtime model within `realtime.fastContext.timeoutMs` before falling back to the full consult agent only if `realtime.fastContext.fallbackToConsult` is true.
 - If `realtime.provider` points at an unregistered provider, or no realtime voice provider is registered at all, Voice Call logs a warning and skips realtime media instead of failing the whole plugin.
-- Consult session keys reuse the stored call session when available, then fall back to the configured `sessionScope` (`per-phone` by default, or `per-call` for isolated calls).
+- Consult session keys reuse the stored call session when available, then fall back to the agent-scoped configured `sessionScope` (`per-phone` by default, or `per-call` for isolated calls).
 
 ### Tool policy
 
diff --git a/extensions/voice-call/src/config.test.ts b/extensions/voice-call/src/config.test.ts
@@ -295,7 +295,23 @@ describe("resolveVoiceCallConfig session routing", () => {
         callId: "call-123",
         phone: "+1 (555) 000-1111",
       }),
-    ).toBe("voice:15550001111");
+    ).toBe("agent:main:voice:15550001111");
+  });
+
+  it("scopes voice sessions by configured agent id", () => {
+    const config = resolveVoiceCallConfig({
+      enabled: true,
+      provider: "mock",
+      agentId: "Cards",
+    });
+
+    expect(
+      resolveVoiceCallSessionKey({
+        config,
+        callId: "call-123",
+        phone: "+1 (555) 000-1111",
+      }),
+    ).toBe("agent:cards:voice:15550001111");
   });
 
   it("can scope voice sessions to each call", () => {
@@ -312,7 +328,7 @@ describe("resolveVoiceCallConfig session routing", () => {
         callId: "call-123",
         phone: "+1 (555) 000-1111",
       }),
-    ).toBe("voice:call:call-123");
+    ).toBe("agent:main:voice:call:call-123");
   });
 
   it("preserves explicit voice session keys", () => {
diff --git a/extensions/voice-call/src/config.ts b/extensions/voice-call/src/config.ts
@@ -1,4 +1,5 @@
 import { REALTIME_VOICE_AGENT_CONSULT_TOOL_POLICIES } from "openclaw/plugin-sdk/realtime-voice";
+import { normalizeAgentId } from "openclaw/plugin-sdk/routing";
 import {
   buildSecretInputSchema,
   hasConfiguredSecretInput,
@@ -717,7 +718,7 @@ export function normalizeVoiceCallConfig(config: VoiceCallConfigInput): VoiceCal
 }
 
 export function resolveVoiceCallSessionKey(params: {
-  config: Pick<VoiceCallConfig, "sessionScope">;
+  config: Pick<VoiceCallConfig, "agentId" | "sessionScope">;
   callId: string;
   phone?: string;
   explicitSessionKey?: string;
@@ -726,11 +727,14 @@ export function resolveVoiceCallSessionKey(params: {
   if (explicit) {
     return explicit;
   }
+  const prefix = `agent:${normalizeAgentId(params.config.agentId)}:voice`;
   if (params.config.sessionScope === "per-call") {
-    return `voice:call:${params.callId}`;
+    return `${prefix}:call:${params.callId}`.toLowerCase();
   }
   const normalizedPhone = params.phone?.replace(/\D/g, "");
-  return normalizedPhone ? `voice:${normalizedPhone}` : `voice:${params.callId}`;
+  return (
+    normalizedPhone ? `${prefix}:${normalizedPhone}` : `${prefix}:${params.callId}`
+  ).toLowerCase();
 }
 
 /**
diff --git a/extensions/voice-call/src/manager/events.test.ts b/extensions/voice-call/src/manager/events.test.ts
@@ -451,7 +451,7 @@ describe("processEvent (functional)", () => {
     processEvent(ctx, event);
 
     const call = requireFirstActiveCall(ctx);
-    expect(call.sessionKey).toBe(`voice:call:${call.callId}`);
+    expect(call.sessionKey).toBe(`agent:main:voice:call:${call.callId}`);
   });
 
   it("applies per-number inbound greeting and stores the matched route key", () => {
diff --git a/extensions/voice-call/src/manager/outbound.test.ts b/extensions/voice-call/src/manager/outbound.test.ts
@@ -194,7 +194,9 @@ describe("voice-call outbound helpers", () => {
     expect(result.success).toBe(true);
     expect(result.callId).toBeTypeOf("string");
     expect(result.callId).not.toBe("");
-    expect(ctx.activeCalls.get(result.callId)?.sessionKey).toBe(`voice:call:${result.callId}`);
+    expect(ctx.activeCalls.get(result.callId)?.sessionKey).toBe(
+      `agent:main:voice:call:${result.callId}`,
+    );
   });
 
   it("initiates conversation calls with pre-connect DTMF TwiML", async () => {
diff --git a/extensions/voice-call/src/response-generator.test.ts b/extensions/voice-call/src/response-generator.test.ts
@@ -206,7 +206,7 @@ describe("generateVoiceResponse", () => {
     });
 
     expect(result.text).toBe("Pinned model works.");
-    const pinnedSessionEntry = sessionStore["voice:15550001111"];
+    const pinnedSessionEntry = sessionStore["agent:main:voice:15550001111"];
     expect(pinnedSessionEntry?.providerOverride).toBe("openai");
     expect(pinnedSessionEntry?.modelOverride).toBe("gpt-4.1-nano");
     expect(pinnedSessionEntry?.modelOverrideSource).toBe("auto");
@@ -219,7 +219,7 @@ describe("generateVoiceResponse", () => {
     const args = requireEmbeddedAgentArgs(runEmbeddedPiAgent);
     expect(args.provider).toBe("openai");
     expect(args.model).toBe("gpt-4.1-nano");
-    expect(args.sessionKey).toBe("voice:15550001111");
+    expect(args.sessionKey).toBe("agent:main:voice:15550001111");
   });
 
   it("uses the persisted per-call session key for classic responses", async () => {
@@ -246,7 +246,7 @@ describe("generateVoiceResponse", () => {
     const perCallSessionEntry = sessionStore["voice:call:call-123"];
     expect(perCallSessionEntry?.sessionId).toBeTypeOf("string");
     expect(perCallSessionEntry?.sessionId).not.toBe("");
-    expect(sessionStore["voice:15550001111"]).toBeUndefined();
+    expect(sessionStore["agent:main:voice:15550001111"]).toBeUndefined();
     const args = requireEmbeddedAgentArgs(runEmbeddedPiAgent);
     expect(args.sessionKey).toBe("voice:call:call-123");
     expect(args.sandboxSessionKey).toBe("agent:main:voice:call:call-123");
@@ -279,7 +279,7 @@ describe("generateVoiceResponse", () => {
     expect(resolveAgentDir).toHaveBeenCalledWith(coreConfig, "main");
     expect(resolveAgentWorkspaceDir).toHaveBeenCalledWith(coreConfig, "main");
     expect(resolveAgentIdentity).toHaveBeenCalledWith(coreConfig, "main");
-    const defaultSessionEntry = sessionStore["voice:15550001111"];
+    const defaultSessionEntry = sessionStore["agent:main:voice:15550001111"];
     if (!defaultSessionEntry) {
       throw new Error("Expected default voice session entry");
     }
@@ -329,7 +329,7 @@ describe("generateVoiceResponse", () => {
     expect(resolveAgentDir).toHaveBeenCalledWith(coreConfig, "voice");
     expect(resolveAgentWorkspaceDir).toHaveBeenCalledWith(coreConfig, "voice");
     expect(resolveAgentIdentity).toHaveBeenCalledWith(coreConfig, "voice");
-    const voiceSessionEntry = sessionStore["voice:15550001111"];
+    const voiceSessionEntry = sessionStore["agent:voice:voice:15550001111"];
     if (!voiceSessionEntry) {
       throw new Error("Expected routed voice session entry");
     }
diff --git a/extensions/voice-call/src/runtime.test.ts b/extensions/voice-call/src/runtime.test.ts
@@ -28,7 +28,7 @@ const mocks = vi.hoisted(() => ({
 
 vi.mock("./config.js", () => ({
   resolveVoiceCallSessionKey: (params: {
-    config: Pick<VoiceCallConfig, "sessionScope">;
+    config: Pick<VoiceCallConfig, "agentId" | "sessionScope">;
     callId: string;
     phone?: string;
     explicitSessionKey?: string;
@@ -37,11 +37,13 @@ vi.mock("./config.js", () => ({
     if (explicit) {
       return explicit;
     }
+    const agentId = params.config.agentId?.trim().toLowerCase() || "main";
+    const prefix = `agent:${agentId}:voice`;
     if (params.config.sessionScope === "per-call") {
-      return `voice:call:${params.callId}`;
+      return `${prefix}:call:${params.callId}`;
     }
     const normalizedPhone = params.phone?.replace(/\D/g, "");
-    return normalizedPhone ? `voice:${normalizedPhone}` : `voice:${params.callId}`;
+    return normalizedPhone ? `${prefix}:${normalizedPhone}` : `${prefix}:${params.callId}`;
   },
   resolveVoiceCallEffectiveConfig: (config: VoiceCallConfig) => ({ config }),
   resolveVoiceCallConfig: mocks.resolveVoiceCallConfig,
@@ -413,7 +415,7 @@ describe("createVoiceCallRuntime lifecycle", () => {
       firstCallParam(runEmbeddedPiAgent.mock.calls as unknown[][], "embedded PI consult"),
       "embedded PI consult params",
     );
-    expect(consultParams.sessionKey).toBe("voice:15550009999");
+    expect(consultParams.sessionKey).toBe("agent:main:voice:15550009999");
     expect(consultParams.spawnedBy).toBe("agent:main:discord:channel:general");
     expect(consultParams.messageProvider).toBe("voice");
     expect(consultParams.lane).toBe("voice");
@@ -558,7 +560,7 @@ describe("createVoiceCallRuntime lifecycle", () => {
         error: console.error,
         debug: console.debug,
       },
-      sessionKey: "voice:15550001234",
+      sessionKey: "agent:main:voice:15550001234",
     });
     expect(runEmbeddedPiAgent).not.toHaveBeenCalled();
   });
