Merge pull request #20 from team-telnyx/bot-config

feat(TALK-16): adding bot configuration tool

Author: ciaranjmp

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-03-25
+
+### Added
+- **BotConfigTool** (`clawtalk_bot_config`): New tool for managing bot settings
+  - `get` action: Read current bot config (name, role, greeting, voice, language, instructions)
+  - `update` action: Update any combination of bot settings
+  - `list_voices` action: Browse 2,200+ TTS voices with filters (provider, language, gender, accent, search)
+  - Voice cache with 5 minute TTL per provider
+  - Results capped at 20 with total count to prevent context bloat
+- **VoicesNamespace** in ClawTalk SDK: `client.voices.list(provider?)` method
+- 22 new tests for BotConfigTool
+
+### Changed
+- **Mission assistant voice inheritance**: `clawtalk_mission_setup_agent` no longer defaults to `Rime.ArcanaV3.astra`
+  - If `voice` param omitted, server now uses user's `voice_preference` (with fallback to system default)
+  - Explicit `voice` param still works for override
+- Updated MissionTool schema description to reflect voice inheritance behavior
+
 ## [0.1.4] - 2026-03-16
 
 ### Removed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawtalk",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Voice calls, SMS, missions, and approvals via ClawTalk — OpenClaw plugin",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

src/lib/clawtalk-sdk/client.ts

@@ -20,6 +20,7 @@ import { MissionsNamespace } from './namespaces/missions.js';
 import { NumbersNamespace } from './namespaces/numbers.js';
 import { SmsNamespace } from './namespaces/sms.js';
 import { UserNamespace } from './namespaces/user.js';
+import { VoicesNamespace } from './namespaces/voices.js';
 
 export interface ClawTalkClientConfig {
   readonly apiKey: string;
@@ -42,6 +43,7 @@ export class ClawTalkClient {
   readonly numbers: NumbersNamespace;
   readonly insights: InsightsNamespace;
   readonly doctor: DoctorNamespace;
+  readonly voices: VoicesNamespace;
 
   private readonly baseUrl: string;
   private readonly headers: Record<string, string>;
@@ -69,6 +71,7 @@ export class ClawTalkClient {
     this.numbers = new NumbersNamespace(request);
     this.insights = new InsightsNamespace(request);
     this.doctor = new DoctorNamespace(request);
+    this.voices = new VoicesNamespace(request);
   }
 
   private async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {

src/lib/clawtalk-sdk/endpoints.ts

@@ -37,6 +37,10 @@ export interface Endpoint {
 export const ENDPOINTS = {
   // ── User (/v1 + user.js) ────────────────────────────────
   getMe: { method: 'GET', path: '/v1/me', sdkMethod: 'getMe', write: false },
+  updateMe: { method: 'PATCH', path: '/v1/me', sdkMethod: 'updateMe', write: true },
+
+  // ── Voices (/v1 + user.js) ───────────────────────────────
+  listVoices: { method: 'GET', path: '/v1/voices', sdkMethod: 'listVoices', write: false },
 
   // ── Calls (/v1/calls + calls.js) ────────────────────────
   initiateCall: { method: 'POST', path: '/v1/calls', sdkMethod: 'initiateCall', write: true },

src/lib/clawtalk-sdk/index.ts

@@ -66,4 +66,6 @@ export type {
   SmsResponse,
   UpdateStepParams,
   UserMeResponse,
+  Voice,
+  VoicesResponse,
 } from './types.js';

src/lib/clawtalk-sdk/namespaces/user.ts

@@ -8,4 +8,8 @@ export class UserNamespace {
   async me(): Promise<UserMeResponse> {
     return this.request<UserMeResponse>('GET', ENDPOINTS.getMe.path);
   }
+
+  async updateMe(fields: Record<string, unknown>): Promise<void> {
+    await this.request('PATCH', ENDPOINTS.updateMe.path, fields);
+  }
 }

src/lib/clawtalk-sdk/namespaces/voices.ts

@@ -0,0 +1,12 @@
+import { ENDPOINTS } from '../endpoints.js';
+import type { VoicesResponse } from '../types.js';
+import type { RequestFn } from './calls.js';
+
+export class VoicesNamespace {
+  constructor(private readonly request: RequestFn) {}
+
+  async list(provider?: string): Promise<VoicesResponse> {
+    const query = provider ? `?provider=${encodeURIComponent(provider)}` : '';
+    return this.request<VoicesResponse>('GET', `${ENDPOINTS.listVoices.path}${query}`);
+  }
+}

src/lib/clawtalk-sdk/types.ts

@@ -36,6 +36,11 @@ export interface UserMeResponse {
   readonly subscription_status: string;
   readonly paranoid_mode: boolean;
   readonly voice_preference: string | null;
+  readonly agent_name: string | null;
+  readonly display_name: string | null;
+  readonly bot_role: string | null;
+  readonly custom_instructions: string | null;
+  readonly greeting: string | null;
   readonly system_number: string | null;
   readonly dedicated_number: string | null;
   readonly totp_enabled: boolean;
@@ -62,6 +67,27 @@ export interface UserMeResponse {
   };
 }
 
+// ── Voices ────────────────────────────────────────────────────
+
+export interface Voice {
+  readonly id: string;
+  readonly name: string;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly language: string;
+  readonly gender: string | null;
+  readonly label: string | null;
+  readonly accent: string | null;
+  readonly age: string | null;
+}
+
+export interface VoicesResponse {
+  readonly default_voice: string;
+  readonly voices: Voice[];
+  readonly providers: string[];
+  readonly total: number;
+}
+
 // ── Calls ─────────────────────────────────────────────────────
 
 export interface InitiateCallParams {

src/services/MissionService.ts

@@ -221,7 +221,7 @@ export class MissionService {
       name: params.name,
       instructions: params.instructions,
       greeting: params.greeting ?? '',
-      voice: params.voice ?? 'Rime.ArcanaV3.astra',
+      voice: params.voice,
       model: params.model ?? 'openai/gpt-4o',
       tools: params.tools as Array<{ type: string; [key: string]: unknown }>,
       enabled_features: params.features ?? ['telephony', 'messaging'],

src/tools/BotConfigTool.ts

@@ -0,0 +1,224 @@
+/**
+ * BotConfigTool — clawtalk_bot_config: Read, update bot configuration, or browse voices.
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { ClawTalkClient } from '../lib/clawtalk-sdk/index.js';
+import type { Voice } from '../lib/clawtalk-sdk/types.js';
+import type { Logger } from '../types/plugin.js';
+import { ToolError } from '../utils/errors.js';
+
+// ── Schema ──────────────────────────────────────────────────
+
+export const BotConfigToolSchema = Type.Object({
+  action: Type.Union([Type.Literal('get'), Type.Literal('update'), Type.Literal('list_voices')]),
+  agent_name: Type.Optional(Type.String({ description: 'Bot name (e.g. Daisy)' })),
+  bot_role: Type.Optional(Type.String({ description: 'Bot role (e.g. live phone voice for Smokies Motels)' })),
+  custom_instructions: Type.Optional(
+    Type.String({ description: 'Custom behaviour instructions, business rules, pricing, etc.' }),
+  ),
+  greeting: Type.Optional(Type.String({ description: 'Greeting spoken when a call connects' })),
+  voice_preference: Type.Optional(Type.String({ description: 'Voice ID (e.g. Rime.ArcanaV3.astra)' })),
+  // list_voices filters
+  provider: Type.Optional(
+    Type.String({
+      description:
+        'Voice provider. Required for list_voices (default: "rime"). Options: rime, minimax, telnyx, inworld, resemble, aws, azure',
+    }),
+  ),
+  language: Type.Optional(Type.String({ description: 'Filter by language code (e.g. "en", "es", "fr-FR")' })),
+  gender: Type.Optional(Type.String({ description: 'Filter by gender ("Male" or "Female")' })),
+  accent: Type.Optional(Type.String({ description: 'Filter by accent (e.g. "British", "Southern American")' })),
+  search: Type.Optional(Type.String({ description: 'Search voice name or label' })),
+});
+
+// ── Voice Cache ─────────────────────────────────────────────
+
+interface CacheEntry {
+  voices: Voice[];
+  providers: string[];
+  defaultVoice: string;
+  fetchedAt: number;
+}
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const voiceCache = new Map<string, CacheEntry>();
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function formatResult(payload: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+function truncate(str: string | null, max: number): string | null {
+  if (!str) return null;
+  return str.length > max ? `${str.slice(0, max - 1)}_` : str;
+}
+
+// ── Tool ─────────────────────────────────────────────────────
+
+export class BotConfigTool {
+  readonly name = 'clawtalk_bot_config';
+  readonly label = 'ClawTalk Bot Config';
+  readonly description =
+    'Read or update the bot configuration (name, role, custom instructions, greeting, voice). Use action "get" to read current config, "update" to change fields, "list_voices" to browse available voices by provider.';
+  readonly parameters = BotConfigToolSchema;
+
+  private readonly client: ClawTalkClient;
+  private readonly logger: Logger;
+
+  constructor(params: { client: ClawTalkClient; logger: Logger }) {
+    this.client = params.client;
+    this.logger = params.logger;
+  }
+
+  async execute(_toolCallId: string, raw: Record<string, unknown>) {
+    const { action } = raw as { action: string };
+
+    if (action === 'get') {
+      return this.handleGet();
+    }
+
+    if (action === 'update') {
+      return this.handleUpdate(raw);
+    }
+
+    if (action === 'list_voices') {
+      return this.handleListVoices(raw);
+    }
+
+    throw new ToolError('clawtalk_bot_config', `Unknown action: ${action}`);
+  }
+
+  private async handleGet() {
+    this.logger.info('Getting bot config');
+    try {
+      const me = await this.client.user.me();
+      const config = {
+        agent_name: me.agent_name ?? null,
+        display_name: me.display_name ?? null,
+        bot_role: me.bot_role ?? 'personal AI assistant',
+        custom_instructions: me.custom_instructions ?? null,
+        greeting: me.greeting ?? null,
+        voice_preference: me.voice_preference ?? null,
+      };
+      return formatResult(config);
+    } catch (err) {
+      throw ToolError.fromError('clawtalk_bot_config', err);
+    }
+  }
+
+  private async handleUpdate(raw: Record<string, unknown>) {
+    this.logger.info('Updating bot config');
+    const fields: Record<string, unknown> = {};
+    for (const key of ['agent_name', 'bot_role', 'custom_instructions', 'greeting', 'voice_preference']) {
+      if (raw[key] !== undefined) fields[key] = raw[key];
+    }
+    if (Object.keys(fields).length === 0) {
+      throw new ToolError('clawtalk_bot_config', 'No fields provided for update');
+    }
+    try {
+      await this.client.user.updateMe(fields);
+      const me = await this.client.user.me();
+      const config = {
+        agent_name: me.agent_name ?? null,
+        display_name: me.display_name ?? null,
+        bot_role: me.bot_role ?? 'personal AI assistant',
+        custom_instructions: me.custom_instructions ?? null,
+        greeting: me.greeting ?? null,
+        voice_preference: me.voice_preference ?? null,
+        message: 'Bot config updated. Changes take effect on the next call.',
+      };
+      return formatResult(config);
+    } catch (err) {
+      throw ToolError.fromError('clawtalk_bot_config', err);
+    }
+  }
+
+  private async handleListVoices(raw: Record<string, unknown>) {
+    const provider = (raw.provider as string) || 'rime';
+    const language = raw.language as string | undefined;
+    const gender = raw.gender as string | undefined;
+    const accent = raw.accent as string | undefined;
+    const search = raw.search as string | undefined;
+
+    this.logger.info(`Listing voices for provider: ${provider}`);
+
+    try {
+      // Check cache
+      const cached = voiceCache.get(provider);
+      let voices: Voice[];
+      let defaultVoice: string;
+      let allProviders: string[];
+
+      if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        voices = cached.voices;
+        defaultVoice = cached.defaultVoice;
+        allProviders = cached.providers;
+      } else {
+        const result = await this.client.voices.list(provider);
+        voices = result.voices;
+        defaultVoice = result.default_voice;
+        allProviders = result.providers;
+        voiceCache.set(provider, {
+          voices,
+          providers: allProviders,
+          defaultVoice,
+          fetchedAt: Date.now(),
+        });
+      }
+
+      // Apply client-side filters
+      let filtered = voices;
+
+      if (language) {
+        const lang = language.toLowerCase();
+        filtered = filtered.filter((v) => v.language.toLowerCase().startsWith(lang));
+      }
+
+      if (gender) {
+        const g = gender.toLowerCase();
+        filtered = filtered.filter((v) => v.gender?.toLowerCase() === g);
+      }
+
+      if (accent) {
+        const a = accent.toLowerCase();
+        filtered = filtered.filter((v) => v.accent?.toLowerCase().includes(a));
+      }
+
+      if (search) {
+        const s = search.toLowerCase();
+        filtered = filtered.filter(
+          (v) =>
+            v.name.toLowerCase().includes(s) ||
+            v.id.toLowerCase().includes(s) ||
+            (v.label?.toLowerCase().includes(s) ?? false),
+        );
+      }
+
+      const totalMatching = filtered.length;
+      const capped = filtered.slice(0, 20);
+
+      return formatResult({
+        default_voice: defaultVoice,
+        provider,
+        providers: allProviders,
+        total_matching: totalMatching,
+        showing: capped.length,
+        voices: capped.map((v) => ({
+          id: v.id,
+          name: v.name,
+          provider: v.provider,
+          language: v.language,
+          gender: v.gender,
+          label: truncate(v.label, 80),
+        })),
+      });
+    } catch (err) {
+      throw ToolError.fromError('clawtalk_bot_config', err);
+    }
+  }
+}