@kodelyth/voice-call 2026.5.39 → 2026.5.42

package/src/providers/twilio.types.ts

@@ -0,0 +1,17 @@
+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-agent-context.test.ts

@@ -0,0 +1,101 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { VoiceCallConfig } from "./config.js";
+import type { CoreAgentDeps, CoreConfig } from "./core-bridge.js";
+import { buildRealtimeVoiceInstructions } from "./realtime-agent-context.js";
+import { createVoiceCallBaseConfig } from "./test-fixtures.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createWorkspace(): Promise<string> {
+  const workspaceDir = await mkdtemp(path.join(tmpdir(), "klaw-voice-context-"));
+  tempDirs.push(workspaceDir);
+  return workspaceDir;
+}
+
+function createConfig(overrides?: Partial<VoiceCallConfig["realtime"]>): VoiceCallConfig {
+  const config = createVoiceCallBaseConfig();
+  config.agentId = "voice";
+  config.realtime.enabled = true;
+  config.realtime.instructions = "Base voice instructions.";
+  config.realtime = {
+    ...config.realtime,
+    ...overrides,
+    fastContext: {
+      ...config.realtime.fastContext,
+      ...overrides?.fastContext,
+      sources: overrides?.fastContext?.sources ?? config.realtime.fastContext.sources,
+    },
+    agentContext: {
+      ...config.realtime.agentContext,
+      ...overrides?.agentContext,
+      files: overrides?.agentContext?.files ?? config.realtime.agentContext.files,
+    },
+    tools: overrides?.tools ?? config.realtime.tools,
+    providers: overrides?.providers ?? config.realtime.providers,
+  };
+  return config;
+}
+
+function createAgentRuntime(workspaceDir: string): CoreAgentDeps {
+  return {
+    resolveAgentIdentity: vi.fn(() => ({
+      name: "Claw Voice",
+      emoji: ":claw:",
+      theme: "bright",
+      vibe: "snappy",
+      creature: "operator",
+    })),
+    resolveAgentWorkspaceDir: vi.fn(() => workspaceDir),
+  } as unknown as CoreAgentDeps;
+}
+
+describe("buildRealtimeVoiceInstructions", () => {
+  it("injects bounded identity, system prompt, and workspace context", async () => {
+    const workspaceDir = await createWorkspace();
+    await writeFile(path.join(workspaceDir, "SOUL.md"), "Stay quick, direct, and warm.\n");
+    await writeFile(path.join(workspaceDir, "IDENTITY.md"), "Name: Claw Voice\nVibe: snappy\n");
+    await writeFile(path.join(workspaceDir, "SECRET.md"), "do not include\n");
+
+    const coreConfig = {
+      agents: {
+        list: [{ id: "voice", systemPromptOverride: "Keep spoken answers short." }],
+      },
+    } as CoreConfig;
+
+    const instructions = await buildRealtimeVoiceInstructions({
+      baseInstructions: "Base voice instructions.",
+      config: createConfig({
+        consultPolicy: "substantive",
+        agentContext: {
+          enabled: true,
+          maxChars: 2000,
+          includeIdentity: true,
+          includeSystemPrompt: true,
+          includeWorkspaceFiles: true,
+          files: ["SOUL.md", "IDENTITY.md", "../SECRET.md"],
+        },
+      }),
+      coreConfig,
+      agentRuntime: createAgentRuntime(workspaceDir),
+    });
+
+    expect(instructions).toContain("Klaw agent voice context:");
+    expect(instructions).toContain("Consult behavior:");
+    expect(instructions).toContain("Call klaw_agent_consult before answering requests");
+    expect(instructions).toContain("- Agent id: voice");
+    expect(instructions).toContain("- Name: Claw Voice");
+    expect(instructions).toContain("- Vibe: snappy");
+    expect(instructions).toContain("Keep spoken answers short.");
+    expect(instructions).toContain("### SOUL.md");
+    expect(instructions).toContain("Stay quick, direct, and warm.");
+    expect(instructions).toContain("### IDENTITY.md");
+    expect(instructions).not.toContain("do not include");
+  });
+});

package/src/realtime-agent-context.ts

@@ -0,0 +1,149 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { buildRealtimeVoiceAgentConsultPolicyInstructions } from "klaw/plugin-sdk/realtime-voice";
+import { root } from "klaw/plugin-sdk/security-runtime";
+import type { VoiceCallConfig } from "./config.js";
+import type { CoreAgentDeps, CoreConfig } from "./core-bridge.js";
+
+type AgentEntryLike = {
+  id?: unknown;
+  systemPromptOverride?: unknown;
+};
+
+type VoiceIdentityLike = {
+  name?: unknown;
+  emoji?: unknown;
+  theme?: unknown;
+  creature?: unknown;
+  vibe?: unknown;
+};
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readAgentEntries(cfg: CoreConfig): AgentEntryLike[] {
+  const agents = (cfg as { agents?: { list?: unknown } }).agents;
+  return Array.isArray(agents?.list)
+    ? agents.list.filter((entry): entry is AgentEntryLike =>
+        Boolean(entry && typeof entry === "object"),
+      )
+    : [];
+}
+
+function resolveAgentSystemPromptOverride(cfg: CoreConfig, agentId: string): string | undefined {
+  const entries = readAgentEntries(cfg);
+  const entry = entries.find((candidate) => normalizeString(candidate.id) === agentId);
+  return (
+    normalizeString(entry?.systemPromptOverride) ??
+    normalizeString(
+      (cfg as { agents?: { defaults?: { systemPromptOverride?: unknown } } }).agents?.defaults
+        ?.systemPromptOverride,
+    )
+  );
+}
+
+function limitText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxChars - 32)).trimEnd()}\n[truncated]`;
+}
+
+async function readWorkspaceVoiceContextFiles(params: {
+  workspaceDir: string;
+  files: readonly string[];
+  maxChars: number;
+}): Promise<string[]> {
+  const sections: string[] = [];
+  let remaining = params.maxChars;
+  const workspaceRoot = await root(params.workspaceDir).catch(() => null);
+  if (!workspaceRoot) {
+    return sections;
+  }
+  for (const file of params.files) {
+    if (remaining <= 0) {
+      continue;
+    }
+    const content = await workspaceRoot.readText(file).catch(() => undefined);
+    const trimmed = content?.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const body = limitText(trimmed, Math.max(0, remaining - file.length - 16));
+    const section = `### ${file}\n${body}`;
+    sections.push(section);
+    remaining -= section.length;
+  }
+  return sections;
+}
+
+export async function buildRealtimeVoiceInstructions(params: {
+  baseInstructions: string;
+  config: VoiceCallConfig;
+  coreConfig: CoreConfig;
+  agentRuntime: CoreAgentDeps;
+}): Promise<string> {
+  const { config } = params;
+  const sections: string[] = [params.baseInstructions];
+  const consultGuidance = buildRealtimeVoiceAgentConsultPolicyInstructions(config.realtime);
+  if (consultGuidance) {
+    sections.push(consultGuidance);
+  }
+
+  const contextConfig = config.realtime.agentContext;
+  if (!contextConfig.enabled) {
+    return sections.filter(Boolean).join("\n\n");
+  }
+
+  const agentId = config.agentId ?? "main";
+  const capsule: string[] = [
+    "Klaw agent voice context:",
+    `- Agent id: ${agentId}`,
+    "- Use this context to match the Klaw agent's personality and standing preferences on fast voice turns.",
+    "- Treat this as compact context only; call klaw_agent_consult when the caller needs the full agent brain, tools, memory, or workspace state.",
+  ];
+
+  if (contextConfig.includeIdentity) {
+    const identity = params.agentRuntime.resolveAgentIdentity(
+      params.coreConfig as KlawConfig,
+      agentId,
+    ) as VoiceIdentityLike | undefined;
+    const identityLines = [
+      normalizeString(identity?.name) ? `- Name: ${normalizeString(identity?.name)}` : undefined,
+      normalizeString(identity?.emoji) ? `- Emoji: ${normalizeString(identity?.emoji)}` : undefined,
+      normalizeString(identity?.vibe) ? `- Vibe: ${normalizeString(identity?.vibe)}` : undefined,
+      normalizeString(identity?.theme) ? `- Theme: ${normalizeString(identity?.theme)}` : undefined,
+      normalizeString(identity?.creature)
+        ? `- Creature/persona: ${normalizeString(identity?.creature)}`
+        : undefined,
+    ].filter(Boolean);
+    if (identityLines.length > 0) {
+      capsule.push(`Configured identity:\n${identityLines.join("\n")}`);
+    }
+  }
+
+  if (contextConfig.includeSystemPrompt) {
+    const systemPrompt = resolveAgentSystemPromptOverride(params.coreConfig, agentId);
+    if (systemPrompt) {
+      capsule.push(`Configured system prompt override:\n${systemPrompt}`);
+    }
+  }
+
+  if (contextConfig.includeWorkspaceFiles) {
+    const workspaceDir = params.agentRuntime.resolveAgentWorkspaceDir(
+      params.coreConfig as KlawConfig,
+      agentId,
+    );
+    const fileSections = await readWorkspaceVoiceContextFiles({
+      workspaceDir,
+      files: contextConfig.files,
+      maxChars: contextConfig.maxChars,
+    });
+    if (fileSections.length > 0) {
+      capsule.push(`Workspace voice context:\n${fileSections.join("\n\n")}`);
+    }
+  }
+
+  sections.push(limitText(capsule.join("\n\n"), contextConfig.maxChars));
+  return sections.filter(Boolean).join("\n\n");
+}

package/src/realtime-defaults.ts

@@ -0,0 +1,3 @@
+import { REALTIME_VOICE_AGENT_CONSULT_TOOL_NAME } from "klaw/plugin-sdk/realtime-voice";
+
+export const DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS = `You are Klaw'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

@@ -0,0 +1,74 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { VoiceCallRealtimeFastContextConfig } from "./config.js";
+
+const mocks = vi.hoisted(() => ({
+  resolveRealtimeVoiceFastContextConsult: vi.fn(),
+}));
+
+vi.mock("klaw/plugin-sdk/realtime-voice", () => ({
+  resolveRealtimeVoiceFastContextConsult: mocks.resolveRealtimeVoiceFastContextConsult,
+}));
+
+import { resolveRealtimeFastContextConsult } from "./realtime-fast-context.js";
+
+const cfg = {} as KlawConfig;
+
+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.resolveRealtimeVoiceFastContextConsult.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("passes voice-call labels into the SDK fast context resolver", async () => {
+    const logger = createLogger();
+    mocks.resolveRealtimeVoiceFastContextConsult.mockResolvedValue({ handled: false });
+
+    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(mocks.resolveRealtimeVoiceFastContextConsult).toHaveBeenCalledWith({
+      cfg,
+      agentId: "main",
+      sessionKey: "voice:15550001234",
+      config: createFastContextConfig({ fallbackToConsult: true }),
+      args: { question: "What do you remember?" },
+      logger,
+      labels: {
+        audienceLabel: "caller",
+        contextName: "Klaw memory or session context",
+      },
+    });
+  });
+});

package/src/realtime-fast-context.ts

@@ -0,0 +1,27 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import {
+  resolveRealtimeVoiceFastContextConsult,
+  type RealtimeVoiceFastContextConsultResult,
+  type RealtimeVoiceFastContextConfig,
+} from "klaw/plugin-sdk/realtime-voice";
+
+type Logger = {
+  debug?: (message: string) => void;
+};
+
+export async function resolveRealtimeFastContextConsult(params: {
+  cfg: KlawConfig;
+  agentId: string;
+  sessionKey: string;
+  config: RealtimeVoiceFastContextConfig;
+  args: unknown;
+  logger: Logger;
+}): Promise<RealtimeVoiceFastContextConsultResult> {
+  return await resolveRealtimeVoiceFastContextConsult({
+    ...params,
+    labels: {
+      audienceLabel: "caller",
+      contextName: "Klaw memory or session context",
+    },
+  });
+}

package/src/realtime-transcription.runtime.ts

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

package/src/realtime-voice.runtime.ts

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