Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/talk-voice/api.ts

@@ -0,0 +1,3 @@
+// Talk Voice API module exposes the plugin public contract.
+export { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+export type { OpenClawPluginApi, PluginRuntime } from "openclaw/plugin-sdk/core";

extensions/talk-voice/index.test.ts

@@ -0,0 +1,402 @@
+// Talk Voice tests cover index plugin behavior.
+import type { OpenClawPluginCommandDefinition } from "openclaw/plugin-sdk/core";
+import { describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "./api.js";
+import register from "./index.js";
+
+function createHarness(initialConfig: Record<string, unknown>) {
+  let config = initialConfig;
+  let command: OpenClawPluginCommandDefinition | undefined;
+  const runtime = {
+    config: {
+      current: vi.fn(() => config),
+      loadConfig: vi.fn(() => config),
+      mutateConfigFile: vi.fn(
+        async ({ mutate }: { mutate: (draft: Record<string, unknown>) => void }) => {
+          const draft = structuredClone(config);
+          mutate(draft);
+          config = draft;
+          return {
+            path: "/tmp/openclaw.json",
+            previousHash: null,
+            persistedHash: null,
+            snapshot: {},
+            nextConfig: config,
+            afterWrite: { mode: "auto" },
+            followUp: { mode: "auto", requiresRestart: false },
+            result: undefined,
+          };
+        },
+      ),
+      replaceConfigFile: vi.fn(async ({ nextConfig }: { nextConfig: Record<string, unknown> }) => {
+        config = nextConfig;
+      }),
+      writeConfigFile: vi.fn().mockResolvedValue(undefined),
+    },
+    tts: {
+      listVoices: vi.fn(),
+    },
+  } as unknown as PluginRuntime;
+  const api = {
+    runtime,
+    registerCommand: vi.fn((definition: OpenClawPluginCommandDefinition) => {
+      command = definition;
+    }),
+  };
+  register.register(api as never);
+  if (!command) {
+    throw new Error("talk-voice command not registered");
+  }
+  return { command, runtime };
+}
+
+function createCommandContext(
+  args: string,
+  channel = "discord",
+  gatewayClientScopes?: string[],
+  senderIsOwner?: boolean,
+) {
+  return {
+    args,
+    channel,
+    channelId: channel,
+    isAuthorizedSender: true,
+    gatewayClientScopes,
+    senderIsOwner,
+    commandBody: args ? `/voice ${args}` : "/voice",
+    config: {},
+    requestConversationBinding: vi.fn(),
+    detachConversationBinding: vi.fn(),
+    getCurrentConversationBinding: vi.fn(),
+  };
+}
+
+describe("talk-voice plugin", () => {
+  function createElevenlabsVoiceSetHarness(channel = "webchat", scopes?: string[]) {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([{ id: "voice-a", name: "Claudia" }]);
+    return {
+      runtime,
+      run: async () => await command.handler(createCommandContext("set Claudia", channel, scopes)),
+    };
+  }
+
+  it("reports active provider status", async () => {
+    const { command } = createHarness({
+      talk: {
+        provider: "microsoft",
+        providers: {
+          microsoft: {
+            voiceId: "en-US-AvaNeural",
+            apiKey: "secret-token",
+          },
+        },
+      },
+    });
+
+    const result = await command.handler(createCommandContext(""));
+
+    expect(result).toEqual({
+      text:
+        "Talk voice status:\n" +
+        "- provider: microsoft\n" +
+        "- talk.providers.microsoft.voiceId: en-US-AvaNeural\n" +
+        "- microsoft.apiKey: secret…",
+    });
+  });
+
+  it("exposes owner status for mutating voice commands", () => {
+    const { command } = createHarness({});
+
+    expect(command.exposeSenderIsOwner).toBe(true);
+  });
+
+  it("lists voices from the active provider", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+            baseUrl: "https://voices.example.test",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([
+      { id: "voice-a", name: "Claudia", category: "general" },
+      { id: "voice-b", name: "Bert" },
+    ]);
+
+    const result = await command.handler(createCommandContext("list +01"));
+
+    expect(runtime.tts.listVoices).toHaveBeenCalledWith({
+      provider: "elevenlabs",
+      cfg: {
+        talk: {
+          provider: "elevenlabs",
+          providers: {
+            elevenlabs: {
+              apiKey: "sk-eleven",
+              baseUrl: "https://voices.example.test",
+            },
+          },
+        },
+      },
+      apiKey: "sk-eleven",
+      baseUrl: "https://voices.example.test",
+    });
+    expect(result).toEqual({
+      text:
+        "ElevenLabs voices: 2\n\n" +
+        "- Claudia · general\n" +
+        "  id: voice-a\n\n" +
+        "(showing first 1)",
+    });
+  });
+
+  it("does not coerce partial voice list limits", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue(
+      Array.from({ length: 13 }, (_, index) => ({
+        id: `voice-${index}`,
+        name: `Voice ${index}`,
+      })),
+    );
+
+    const result = await command.handler(createCommandContext("list 1x"));
+
+    expect(result.text).toContain("(showing first 12)");
+  });
+
+  it("surfaces richer provider voice metadata when available", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "microsoft",
+        providers: {
+          microsoft: {},
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([
+      {
+        id: "en-US-AvaNeural",
+        name: "Ava",
+        category: "General",
+        locale: "en-US",
+        gender: "Female",
+        personalities: ["Friendly", "Positive"],
+        description: "Friendly, Positive",
+      },
+    ]);
+
+    const result = await command.handler(createCommandContext("list"));
+
+    expect(result).toEqual({
+      text:
+        "Microsoft voices: 1\n\n" +
+        "- Ava · General\n" +
+        "  id: en-US-AvaNeural\n" +
+        "  meta: en-US · Female · Friendly, Positive\n" +
+        "  note: Friendly, Positive",
+    });
+  });
+
+  it("writes canonical talk provider config and legacy elevenlabs voice id", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([{ id: "voice-a", name: "Claudia" }]);
+
+    const result = await command.handler(
+      createCommandContext("set Claudia", "webchat", ["operator.admin"]),
+    );
+
+    expect(runtime.config.mutateConfigFile).toHaveBeenCalledWith({
+      afterWrite: { mode: "auto" },
+      mutate: expect.any(Function),
+    });
+    expect(runtime.config.current()).toEqual({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+            voiceId: "voice-a",
+          },
+        },
+        voiceId: "voice-a",
+      },
+    });
+    expect(result).toEqual({
+      text: "✅ ElevenLabs Talk voice set to Claudia\nvoice-a",
+    });
+  });
+
+  it("writes provider voice id without legacy top-level field for microsoft", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "microsoft",
+        providers: {
+          microsoft: {},
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([{ id: "en-US-AvaNeural", name: "Ava" }]);
+
+    await command.handler(createCommandContext("set Ava", "webchat", ["operator.admin"]));
+
+    expect(runtime.config.mutateConfigFile).toHaveBeenCalledWith({
+      afterWrite: { mode: "auto" },
+      mutate: expect.any(Function),
+    });
+    expect(runtime.config.current()).toEqual({
+      talk: {
+        provider: "microsoft",
+        providers: {
+          microsoft: {
+            voiceId: "en-US-AvaNeural",
+          },
+        },
+      },
+    });
+  });
+
+  it("rejects /voice set from gateway client with only operator.write scope", async () => {
+    const { runtime, run } = createElevenlabsVoiceSetHarness("webchat", ["operator.write"]);
+    const result = await run();
+
+    expect(result.text).toContain("requires operator.admin");
+    expect(runtime.config.mutateConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("rejects /voice set from non-webchat gateway callers missing operator.admin", async () => {
+    const { runtime, run } = createElevenlabsVoiceSetHarness("telegram", ["operator.write"]);
+    const result = await run();
+
+    expect(result.text).toContain("requires operator.admin");
+    expect(runtime.config.mutateConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("allows /voice set from gateway client with operator.admin scope", async () => {
+    const { runtime, run } = createElevenlabsVoiceSetHarness("webchat", ["operator.admin"]);
+    const result = await run();
+
+    expect(runtime.config.mutateConfigFile).toHaveBeenCalled();
+    expect(result.text).toContain("voice-a");
+  });
+
+  it("rejects /voice set from webchat channel with no scopes (TUI/internal)", async () => {
+    const { runtime, run } = createElevenlabsVoiceSetHarness();
+    const result = await run();
+
+    expect(result.text).toContain("requires operator.admin");
+    expect(runtime.config.mutateConfigFile).not.toHaveBeenCalled();
+  });
+
+  it.each(["telegram", "discord"])(
+    "rejects /voice set from %s channel without operator.admin",
+    async (channel) => {
+      const { runtime, run } = createElevenlabsVoiceSetHarness(channel);
+      const result = await run();
+
+      expect(result.text).toContain("requires operator.admin");
+      expect(runtime.config.mutateConfigFile).not.toHaveBeenCalled();
+    },
+  );
+
+  it("keeps read-only voice commands available without operator.admin", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([{ id: "voice-a", name: "Claudia" }]);
+
+    const status = await command.handler(createCommandContext("status", "telegram"));
+    const list = await command.handler(createCommandContext("list", "telegram"));
+
+    expect(status.text).toContain("Talk voice status:");
+    expect(list.text).toContain("ElevenLabs voices: 1");
+    expect(runtime.config.mutateConfigFile).not.toHaveBeenCalled();
+  });
+
+  it("allows /voice set when operator.admin is present on a non-webchat channel", async () => {
+    const { runtime, run } = createElevenlabsVoiceSetHarness("telegram", ["operator.admin"]);
+    const result = await run();
+
+    expect(runtime.config.mutateConfigFile).toHaveBeenCalled();
+    expect(result.text).toContain("voice-a");
+  });
+
+  it("allows /voice set from an owner non-gateway channel without scopes", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "elevenlabs",
+        providers: {
+          elevenlabs: {
+            apiKey: "sk-eleven",
+          },
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockResolvedValue([{ id: "voice-a", name: "Claudia" }]);
+
+    const result = await command.handler(
+      createCommandContext("set Claudia", "telegram", undefined, true),
+    );
+
+    expect(runtime.config.mutateConfigFile).toHaveBeenCalled();
+    expect(result.text).toContain("voice-a");
+  });
+
+  it("returns provider lookup errors cleanly", async () => {
+    const { command, runtime } = createHarness({
+      talk: {
+        provider: "microsoft",
+        providers: {
+          microsoft: {},
+        },
+      },
+    });
+    vi.mocked(runtime.tts.listVoices).mockRejectedValue(
+      new Error("speech provider microsoft does not support voice listing"),
+    );
+
+    const result = await command.handler(createCommandContext("list"));
+
+    expect(result).toEqual({
+      text: "Microsoft voice list failed: speech provider microsoft does not support voice listing",
+    });
+  });
+});

extensions/talk-voice/index.ts

@@ -0,0 +1,263 @@
+// Talk Voice plugin entrypoint registers its OpenClaw integration.
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
+import type { SpeechVoiceOption } from "openclaw/plugin-sdk/speech";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+} from "openclaw/plugin-sdk/string-coerce-runtime";
+import { resolveActiveTalkProviderConfig } from "openclaw/plugin-sdk/talk-config-runtime";
+import { definePluginEntry, type OpenClawPluginApi } from "./api.js";
+
+function mask(s: string, keep = 6): string {
+  const trimmed = s.trim();
+  if (trimmed.length <= keep) {
+    return "***";
+  }
+  return `${trimmed.slice(0, keep)}…`;
+}
+
+function isLikelyVoiceId(value: string): boolean {
+  const v = value.trim();
+  if (v.length < 10 || v.length > 64) {
+    return false;
+  }
+  return /^[a-zA-Z0-9_-]+$/.test(v);
+}
+
+function resolveProviderLabel(providerId: string): string {
+  switch (providerId) {
+    case "openai":
+      return "OpenAI";
+    case "microsoft":
+      return "Microsoft";
+    case "elevenlabs":
+      return "ElevenLabs";
+    default:
+      return providerId;
+  }
+}
+
+function formatVoiceMeta(voice: SpeechVoiceOption): string | undefined {
+  const parts = [voice.locale, voice.gender];
+  const personalities = voice.personalities?.filter((value) => value.trim().length > 0) ?? [];
+  if (personalities.length > 0) {
+    parts.push(personalities.join(", "));
+  }
+  const filtered = parts.filter((part): part is string => Boolean(part?.trim()));
+  return filtered.length > 0 ? filtered.join(" · ") : undefined;
+}
+
+function formatVoiceList(voices: SpeechVoiceOption[], limit: number, providerId: string): string {
+  const sliced = voices.slice(0, Math.max(1, Math.min(limit, 50)));
+  const lines: string[] = [];
+  lines.push(`${resolveProviderLabel(providerId)} voices: ${voices.length}`);
+  lines.push("");
+  for (const v of sliced) {
+    const name = (v.name ?? "").trim() || "(unnamed)";
+    const category = (v.category ?? "").trim();
+    const meta = category ? ` · ${category}` : "";
+    lines.push(`- ${name}${meta}`);
+    lines.push(`  id: ${v.id}`);
+    const details = formatVoiceMeta(v);
+    if (details) {
+      lines.push(`  meta: ${details}`);
+    }
+    const description = (v.description ?? "").trim();
+    if (description) {
+      lines.push(`  note: ${description}`);
+    }
+  }
+  if (voices.length > sliced.length) {
+    lines.push("");
+    lines.push(`(showing first ${sliced.length})`);
+  }
+  return lines.join("\n");
+}
+
+function findVoice(voices: SpeechVoiceOption[], query: string): SpeechVoiceOption | null {
+  const q = query.trim();
+  if (!q) {
+    return null;
+  }
+  const lower = normalizeLowercaseStringOrEmpty(q);
+  const byId = voices.find((v) => v.id === q);
+  if (byId) {
+    return byId;
+  }
+  const exactName = voices.find((v) => normalizeOptionalLowercaseString(v.name) === lower);
+  if (exactName) {
+    return exactName;
+  }
+  const partial = voices.find((v) => normalizeLowercaseStringOrEmpty(v.name).includes(lower));
+  return partial ?? null;
+}
+
+function asTrimmedString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function parsePositiveIntegerToken(value: unknown): number | undefined {
+  return parseStrictPositiveInteger(value);
+}
+
+function resolveCommandLabel(channel: string): string {
+  return channel === "discord" ? "/talkvoice" : "/voice";
+}
+
+function asProviderBaseUrl(value: unknown): string | undefined {
+  const trimmed = asTrimmedString(value);
+  return trimmed || undefined;
+}
+
+const TALK_ADMIN_SCOPE = "operator.admin";
+
+function requiresAdminToSetVoice(params: {
+  senderIsOwner?: boolean;
+  gatewayClientScopes?: readonly string[];
+}): boolean {
+  const { senderIsOwner, gatewayClientScopes } = params;
+  if (Array.isArray(gatewayClientScopes)) {
+    return !gatewayClientScopes.includes(TALK_ADMIN_SCOPE);
+  }
+  return senderIsOwner !== true;
+}
+
+export default definePluginEntry({
+  id: "talk-voice",
+  name: "Talk Voice",
+  description: "Command helpers for managing Talk voice configuration",
+  register(api: OpenClawPluginApi) {
+    api.registerCommand({
+      name: "voice",
+      nativeNames: {
+        discord: "talkvoice",
+      },
+      description: "List/set Talk provider voices (affects iOS Talk playback).",
+      acceptsArgs: true,
+      exposeSenderIsOwner: true,
+      handler: async (ctx) => {
+        const commandLabel = resolveCommandLabel(ctx.channel);
+        const args = ctx.args?.trim() ?? "";
+        const tokens = args.split(/\s+/).filter(Boolean);
+        const action = normalizeLowercaseStringOrEmpty(tokens[0] ?? "status");
+
+        const cfg = api.runtime.config.current() as OpenClawConfig;
+        const active = resolveActiveTalkProviderConfig(cfg.talk);
+        if (!active) {
+          return {
+            text:
+              "Talk voice is not configured.\n\n" +
+              "Missing: talk.provider and talk.providers.<provider>.\n" +
+              "Set it on the gateway, then retry.",
+          };
+        }
+        const providerId = active.provider;
+        const providerLabel = resolveProviderLabel(providerId);
+        const apiKey = asTrimmedString(active.config.apiKey);
+        const baseUrl = asProviderBaseUrl(active.config.baseUrl);
+
+        const currentVoiceId = asTrimmedString(active.config.voiceId);
+
+        if (action === "status") {
+          return {
+            text:
+              "Talk voice status:\n" +
+              `- provider: ${providerId}\n` +
+              `- talk.providers.${providerId}.voiceId: ${currentVoiceId ? currentVoiceId : "(unset)"}\n` +
+              `- ${providerId}.apiKey: ${apiKey ? mask(apiKey) : "(unset)"}`,
+          };
+        }
+
+        if (action === "list") {
+          const limit = parsePositiveIntegerToken(tokens[1]) ?? 12;
+          try {
+            const voices = await api.runtime.tts.listVoices({
+              provider: providerId,
+              cfg,
+              apiKey: apiKey || undefined,
+              baseUrl,
+            });
+            return {
+              text: formatVoiceList(voices, limit, providerId),
+            };
+          } catch (error) {
+            const message = formatErrorMessage(error);
+            return { text: `${providerLabel} voice list failed: ${message}` };
+          }
+        }
+
+        if (action === "set") {
+          // Persistent Talk voice changes are gateway config writes, so the
+          // mutating subcommand requires explicit admin or owner authority.
+          if (
+            requiresAdminToSetVoice({
+              senderIsOwner: ctx.senderIsOwner,
+              gatewayClientScopes: ctx.gatewayClientScopes,
+            })
+          ) {
+            return { text: `⚠️ ${commandLabel} set requires operator.admin.` };
+          }
+
+          const query = tokens.slice(1).join(" ").trim();
+          if (!query) {
+            return { text: `Usage: ${commandLabel} set <voiceId|name>` };
+          }
+          let voices: SpeechVoiceOption[];
+          try {
+            voices = await api.runtime.tts.listVoices({
+              provider: providerId,
+              cfg,
+              apiKey: apiKey || undefined,
+              baseUrl,
+            });
+          } catch (error) {
+            const message = formatErrorMessage(error);
+            return { text: `${providerLabel} voice lookup failed: ${message}` };
+          }
+          const chosen = findVoice(voices, query);
+          if (!chosen) {
+            const hint = isLikelyVoiceId(query) ? query : `"${query}"`;
+            return { text: `No voice found for ${hint}. Try: ${commandLabel} list` };
+          }
+
+          await api.runtime.config.mutateConfigFile({
+            afterWrite: { mode: "auto" },
+            mutate: (draft) => {
+              const nextConfig = {
+                ...draft,
+                talk: {
+                  ...draft.talk,
+                  provider: providerId,
+                  providers: {
+                    ...draft.talk?.providers,
+                    [providerId]: {
+                      ...draft.talk?.providers?.[providerId],
+                      voiceId: chosen.id,
+                    },
+                  },
+                  ...(providerId === "elevenlabs" ? { voiceId: chosen.id } : {}),
+                },
+              };
+              Object.assign(draft, nextConfig);
+            },
+          });
+
+          const name = (chosen.name ?? "").trim() || "(unnamed)";
+          return { text: `✅ ${providerLabel} Talk voice set to ${name}\n${chosen.id}` };
+        }
+
+        return {
+          text: [
+            "Voice commands:",
+            "",
+            `${commandLabel} status`,
+            `${commandLabel} list [limit]`,
+            `${commandLabel} set <voiceId|name>`,
+          ].join("\n"),
+        };
+      },
+    });
+  },
+});

extensions/talk-voice/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "talk-voice",
+  "activation": {
+    "onStartup": true
+  },
+  "enabledByDefault": true,
+  "name": "Talk Voice",
+  "description": "Manage Talk voice selection (list/set).",
+  "commandAliases": [
+    {
+      "name": "voice",
+      "kind": "runtime-slash"
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}