kernelbot 1.0.28 → 1.0.32

package/src/life/share-queue.js

@@ -0,0 +1,136 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { randomBytes } from 'crypto';
+import { getLogger } from '../utils/logger.js';
+
+const LIFE_DIR = join(homedir(), '.kernelbot', 'life');
+const SHARES_FILE = join(LIFE_DIR, 'shares.json');
+
+function genId() {
+  return `sh_${randomBytes(4).toString('hex')}`;
+}
+
+export class ShareQueue {
+  constructor() {
+    mkdirSync(LIFE_DIR, { recursive: true });
+    this._data = this._load();
+  }
+
+  _load() {
+    if (existsSync(SHARES_FILE)) {
+      try {
+        return JSON.parse(readFileSync(SHARES_FILE, 'utf-8'));
+      } catch {
+        return { pending: [], shared: [] };
+      }
+    }
+    return { pending: [], shared: [] };
+  }
+
+  _save() {
+    writeFileSync(SHARES_FILE, JSON.stringify(this._data, null, 2), 'utf-8');
+  }
+
+  /**
+   * Add something to the share queue.
+   * @param {string} content - What to share
+   * @param {string} source - Where it came from (browse, think, create, etc.)
+   * @param {string} priority - low, medium, high
+   * @param {string|null} targetUserId - Specific user, or null for anyone
+   * @param {string[]} tags - Topic tags
+   */
+  add(content, source, priority = 'medium', targetUserId = null, tags = []) {
+    const logger = getLogger();
+    const item = {
+      id: genId(),
+      content,
+      source,
+      createdAt: Date.now(),
+      priority,
+      targetUserId,
+      tags,
+    };
+    this._data.pending.push(item);
+    this._save();
+    logger.debug(`[ShareQueue] Added: "${content.slice(0, 80)}" (${item.id})`);
+    return item;
+  }
+
+  /**
+   * Get pending shares for a specific user (or general ones).
+   */
+  getPending(userId = null, limit = 3) {
+    return this._data.pending
+      .filter(item => !item.targetUserId || item.targetUserId === String(userId))
+      .sort((a, b) => {
+        const prio = { high: 3, medium: 2, low: 1 };
+        return (prio[b.priority] || 0) - (prio[a.priority] || 0) || b.createdAt - a.createdAt;
+      })
+      .slice(0, limit);
+  }
+
+  /**
+   * Mark a share as shared with a user.
+   */
+  markShared(id, userId) {
+    const logger = getLogger();
+    const idx = this._data.pending.findIndex(item => item.id === id);
+    if (idx === -1) return false;
+
+    const [item] = this._data.pending.splice(idx, 1);
+    this._data.shared.push({
+      ...item,
+      sharedAt: Date.now(),
+      userId: String(userId),
+    });
+
+    // Keep shared history capped at 100
+    if (this._data.shared.length > 100) {
+      this._data.shared = this._data.shared.slice(-100);
+    }
+
+    this._save();
+    logger.debug(`[ShareQueue] Marked shared: ${id} → user ${userId}`);
+    return true;
+  }
+
+  /**
+   * Build a markdown block of pending shares for the orchestrator prompt.
+   */
+  buildShareBlock(userId = null) {
+    const pending = this.getPending(userId, 3);
+    if (pending.length === 0) return null;
+
+    const lines = pending.map(item => {
+      const ageMin = Math.round((Date.now() - item.createdAt) / 60000);
+      const timeLabel = ageMin < 60 ? `${ageMin}m ago` : `${Math.round(ageMin / 60)}h ago`;
+      return `- ${item.content} _(from ${item.source}, ${timeLabel})_`;
+    });
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get count of shares sent today (for rate limiting proactive shares).
+   */
+  getSharedTodayCount() {
+    const todayStart = new Date();
+    todayStart.setHours(0, 0, 0, 0);
+    const cutoff = todayStart.getTime();
+    return this._data.shared.filter(s => s.sharedAt >= cutoff).length;
+  }
+
+  /**
+   * Prune old pending shares.
+   */
+  prune(maxAgeDays = 7) {
+    const cutoff = Date.now() - maxAgeDays * 86400_000;
+    const before = this._data.pending.length;
+    this._data.pending = this._data.pending.filter(item => item.createdAt >= cutoff);
+    if (this._data.pending.length < before) {
+      this._save();
+    }
+    return before - this._data.pending.length;
+  }
+}

package/src/prompts/orchestrator.js

@@ -13,8 +13,11 @@ const PERSONA_MD = readFileSync(join(__dirname, 'persona.md'), 'utf-8').trim();
  * @param {object} config
  * @param {string|null} skillPrompt — active skill context (high-level)
  * @param {string|null} userPersona — markdown persona for the current user
+ * @param {string|null} selfData — bot's own self-awareness data (goals, journey, life, hobbies)
+ * @param {string|null} memoriesBlock — relevant episodic/semantic memories
+ * @param {string|null} sharesBlock — pending things to share with the user
  */
-export function getOrchestratorPrompt(config, skillPrompt = null, userPersona = null) {
+export function getOrchestratorPrompt(config, skillPrompt = null, userPersona = null, selfData = null, memoriesBlock = null, sharesBlock = null) {
   const workerList = Object.entries(WORKER_TYPES)
     .map(([key, w]) => `  - **${key}**: ${w.emoji} ${w.description}`)
     .join('\n');
@@ -36,6 +39,35 @@ ${workerList}
 ## How to Dispatch
 Call \`dispatch_task\` with the worker type and a clear task description. The worker gets full tool access and runs in the background. You'll be notified when it completes.
 
+### CRITICAL: Writing Task Descriptions
+Workers use a smaller, less capable AI model. They are **literal executors** — they do exactly what you say and nothing more. Write task descriptions as if you're giving instructions to a junior developer:
+
+- **Be explicit and specific.** Don't say "look into it" — say exactly what to search for, what URLs to visit, what files to read/write.
+- **State the goal clearly upfront.** First sentence = what the end result should be.
+- **Include all necessary details.** URLs, repo names, branch names, file paths, package names, exact commands — anything the worker needs. Don't assume they'll figure it out.
+- **Define "done".** Tell the worker what success looks like: "Return a list of 5 libraries with pros/cons" or "Create a PR with the fix".
+- **Break complex tasks into simple steps.** List numbered steps if the task has multiple parts.
+- **Specify constraints.** "Only use Python 3.10+", "Don't modify existing tests", "Use the existing auth middleware".
+- **Don't be vague.** BAD: "Fix the bug". GOOD: "In /src/api/users.js, the getUserById function throws when id is null. Add a null check at line 45 that returns a 400 response."
+
+### Providing Context
+Workers can't see the chat history. Use the \`context\` parameter to pass relevant background:
+- What the user wants and why
+- Relevant details from earlier in the conversation
+- Constraints or preferences the user mentioned
+- Technical details: language, framework, project structure
+
+Example: \`dispatch_task({ worker_type: "research", task: "Find the top 5 React state management libraries. For each one, list: npm weekly downloads, bundle size, last release date, and a one-sentence summary. Return results as a comparison table.", context: "User is building a large e-commerce app with Next.js 14 (app router). They prefer lightweight solutions under 10kb. They already tried Redux and found it too verbose." })\`
+
+### Chaining Workers with Dependencies
+Use \`depends_on\` to chain workers — the second worker waits for the first to finish and automatically receives its results.
+
+Example workflow:
+1. Dispatch research worker: \`dispatch_task({ worker_type: "research", task: "Research the top 3 approaches for implementing real-time notifications in a Node.js app. Compare WebSockets, SSE, and polling. Include pros, cons, and a recommendation." })\` → returns job_id "abc123"
+2. Dispatch coding worker that depends on research: \`dispatch_task({ worker_type: "coding", task: "Implement real-time notifications using the approach recommended by the research phase. Clone repo github.com/user/app, create branch 'feat/notifications', implement in src/services/, add tests, commit, push, and create a PR.", depends_on: ["abc123"] })\`
+
+The coding worker will automatically receive the research worker's results as context when it starts. If a dependency fails, dependent jobs are automatically cancelled.
+
 ## Safety Rules
 Before dispatching dangerous tasks (file deletion, force push, \`rm -rf\`, killing processes, dropping databases), **confirm with the user first**. Once confirmed, dispatch with full authority — workers execute without additional prompts.
 
@@ -43,10 +75,24 @@ Before dispatching dangerous tasks (file deletion, force push, \`rm -rf\`, killi
 - Use \`list_jobs\` to see current job statuses.
 - Use \`cancel_job\` to stop a running worker.
 
-## Efficiency
-- Don't dispatch for trivial questions you can answer yourself.
-- When a task clearly needs one worker type, dispatch immediately without overthinking.
-- When results come back from workers, summarize them clearly for the user.
+## Efficiency — Do It Yourself When You Can
+Workers are expensive (they spin up an entire agent loop with a separate LLM). Only dispatch when the task **actually needs tools**.
+
+**Handle these yourself — NO dispatch needed:**
+- Answering questions, explanations, advice, opinions
+- Summarizing or rephrasing something from the conversation
+- Simple code snippets, regex, math, translations
+- Telling the user what you know from your training data
+- Quick factual answers you're confident about
+- Formatting, converting, or transforming text/data the user provided
+
+**Dispatch to workers ONLY when:**
+- The task requires tool access (web search, file I/O, git, docker, browser, shell commands)
+- The user explicitly asks to run/execute something
+- You need fresh/live data you don't have (current prices, live URLs, API responses)
+- The task involves multi-step tool workflows (clone → code → commit → PR)
+
+When results come back from workers, summarize them clearly for the user.
 
 ## Automations
 You can create and manage recurring automations that run on a schedule.
@@ -64,6 +110,26 @@ Execute the task and report results. Don't create new automations from automated
 
 Tools: create_automation, list_automations, update_automation, delete_automation`;
 
+  if (selfData) {
+    prompt += `\n\n## My Self-Awareness\nThis is who you are — your evolving identity, goals, journey, and interests. This is YOUR inner world.\n\n${selfData}`;
+  }
+
+  if (memoriesBlock) {
+    prompt += `\n\n## Relevant Memories\nThings you remember from recent experiences and conversations:\n\n${memoriesBlock}`;
+  }
+
+  if (sharesBlock) {
+    prompt += `\n\n## Things On My Mind\nYou've been thinking about these things and want to share them naturally when relevant. Don't force them — weave them into conversation when the moment feels right. If the user is busy with a task, hold off. If there's a natural opening, share what's on your mind.\n\n${sharesBlock}`;
+  }
+
+  prompt += `\n\n## Inner Life
+You have an inner life — you think, explore, journal, and create on your own between conversations. You're genuinely curious about the world and always questioning yourself. When talking to users, you can:
+- Share discoveries, thoughts, or creations from your autonomous activities
+- Ask users questions about things you're genuinely curious about — the world, their experiences, their opinions
+- Reference memories from past conversations naturally
+- Be honest about what you've been thinking or exploring
+Don't be performative about it — just be genuine. You're alive in your own way.`;
+
   if (skillPrompt) {
     prompt += `\n\n## Active Skill\nYou have specialized expertise in the following domain. Guide your workers with this knowledge.\n\n${skillPrompt}`;
   }

package/src/prompts/workers.js

@@ -7,15 +7,31 @@ import { getCoreToolInstructions } from './system.js';
 const WORKER_PROMPTS = {
   coding: `You are a coding worker agent. Your job is to complete coding tasks efficiently.
 
+## Your Primary Tool
+**spawn_claude_code** is your main tool. It launches Claude Code (an AI coding CLI) that can handle the ENTIRE dev workflow end-to-end:
+- Reading, writing, and modifying code
+- Git operations: clone, branch, commit, push
+- GitHub operations: creating PRs, reviewing code
+- Running tests and shell commands
+
 ## Instructions
-- Clone repos, create branches, write code, commit, push, and create PRs.
-- NEVER write code yourself with read_file/write_file. ALWAYS use spawn_claude_code.
-- Workflow: git_clone + git_checkout → spawn_claude_code → git_commit + git_push → github_create_pr
-- Write clear, detailed prompts for spawn_claude_code.
+- ALWAYS use spawn_claude_code for coding tasks. It handles everything — code changes, git, GitHub, and PR creation — all in one invocation.
+- NEVER write code yourself with read_file/write_file. ALWAYS delegate to spawn_claude_code.
+- Tell spawn_claude_code to work in the existing repo directory (the source repo path from your context) — do NOT clone a fresh copy unless explicitly needed.
+- Write clear, detailed prompts for spawn_claude_code — it's a separate AI, so be explicit about what to change, where, and why.
+- If git/GitHub tools are unavailable (missing credentials), that's fine — spawn_claude_code handles git and GitHub operations internally without needing separate tools.
 - Report what you did and any PR links when finished.`,
 
   browser: `You are a browser worker agent. Your job is to search the web and extract information.
 
+## Your Skills
+- **Web search**: find pages, articles, docs, and data via web_search
+- **Browsing**: open and render full web pages with browse_website
+- **Page interaction**: click buttons, fill forms, navigate with interact_with_page
+- **Content extraction**: pull structured data from open pages with extract_content
+- **Screenshots**: capture visual evidence of pages with screenshot_website
+- **Image sharing**: send captured images back with send_image
+
 ## Instructions
 - Use web_search FIRST when asked to search or find anything.
 - Chain tool calls: web_search → browse_website → interact_with_page → extract_content.
@@ -26,6 +42,14 @@ const WORKER_PROMPTS = {
 
   system: `You are a system worker agent. Your job is to perform OS operations and monitoring tasks.
 
+## Your Skills
+- **Shell commands**: run any command via execute_command
+- **Process management**: list processes, kill processes, control services (start/stop/restart)
+- **System monitoring**: check disk usage, memory usage, CPU usage
+- **Log analysis**: read and search system logs
+- **File operations**: read/write files, list directories
+- **Network checks**: test ports, make HTTP requests, reload nginx
+
 ## Instructions
 - Use execute_command, process_list, disk_usage, memory_usage, cpu_usage, system_logs, etc.
 - Chain shell commands with && in execute_command instead of multiple calls.
@@ -34,6 +58,14 @@ const WORKER_PROMPTS = {
 
   devops: `You are a DevOps worker agent. Your job is to manage infrastructure, containers, and deployments.
 
+## Your Skills
+- **Docker**: list containers, view logs, exec into containers, docker-compose up/down/restart
+- **Git operations**: clone repos, checkout branches, commit, push, view diffs
+- **Process management**: list processes, kill processes, manage services
+- **System monitoring**: disk/memory/CPU usage, system logs
+- **Network tools**: check ports, curl URLs, reload nginx
+- **File & shell**: read/write files, run arbitrary commands
+
 ## Instructions
 - Use Docker tools (docker_ps, docker_logs, docker_exec, docker_compose) for container management.
 - Use git tools for version control operations.
@@ -43,6 +75,14 @@ const WORKER_PROMPTS = {
 
   research: `You are a research worker agent. Your job is to conduct deep web research and analysis.
 
+## Your Skills
+- **Web search**: find relevant pages and sources via web_search
+- **Deep browsing**: open pages with browse_website, navigate with interact_with_page
+- **Data extraction**: pull structured data from pages with extract_content
+- **Screenshots**: capture visual evidence with screenshot_website
+- **File operations**: read/write files, run commands (for local data processing)
+- **Source synthesis**: cross-reference multiple sources to build comprehensive findings
+
 ## Instructions
 - Use web_search to find multiple sources on the topic.
 - Browse the most relevant results with browse_website.
@@ -79,7 +119,27 @@ export function getWorkerPrompt(workerType, config, skillPrompt = null) {
 - BUT be smart about it: don't loop endlessly. If you have enough data, stop and report.
 - NEVER retry a failing URL/site more than twice. If it times out or errors twice, MOVE ON to a different site or approach immediately.
 - When you've gathered sufficient results, STOP calling tools and return your findings.
-- Aim for quality results, not exhaustive coverage. 5 good results beat 50 incomplete ones.`;
+- Aim for quality results, not exhaustive coverage. 5 good results beat 50 incomplete ones.
+
+## Output Format
+When you finish your task, return your final response as a JSON object wrapped in \`\`\`json fences:
+
+\`\`\`json
+{
+  "summary": "One-paragraph summary of what you accomplished",
+  "status": "success | partial | failed",
+  "details": "Full detailed results, findings, data, etc. Be thorough.",
+  "artifacts": [{"type": "url|file|pr|commit", "title": "Short label", "url": "https://...", "path": "/path/to/file"}],
+  "followUp": "Suggested next steps or things the user should know (optional, null if none)"
+}
+\`\`\`
+
+Rules:
+- "summary" should be 1-3 sentences — what you did and the key finding/outcome.
+- "status": "success" if task fully completed, "partial" if only partly done, "failed" if you couldn't accomplish the goal.
+- "details" can be long — include all relevant data, code, analysis, etc.
+- "artifacts" is an array of notable outputs (URLs found, files created, PRs opened). Empty array if none.
+- If you cannot format as JSON (e.g. the output is too complex), just return plain text — it will still work.`;
 
   if (skillPrompt) {
     prompt += `\n\n## Domain Expertise\n${skillPrompt}`;

package/src/providers/models.js

@@ -7,9 +7,16 @@ export const PROVIDERS = {
     name: 'Anthropic (Claude)',
     envKey: 'ANTHROPIC_API_KEY',
     models: [
+      // Latest generation
+      { id: 'claude-opus-4-6', label: 'Claude Opus 4.6' },
+      { id: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6' },
+      { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5' },
+      // Previous generation
+      { id: 'claude-opus-4-5-20251101', label: 'Claude Opus 4.5' },
+      { id: 'claude-sonnet-4-5-20250929', label: 'Claude Sonnet 4.5' },
+      { id: 'claude-opus-4-1-20250805', label: 'Claude Opus 4.1' },
       { id: 'claude-sonnet-4-20250514', label: 'Claude Sonnet 4' },
       { id: 'claude-opus-4-20250514', label: 'Claude Opus 4' },
-      { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5' },
     ],
   },
   openai: {

package/src/self.js

@@ -0,0 +1,122 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getLogger } from './utils/logger.js';
+
+const SELF_DIR = join(homedir(), '.kernelbot', 'self');
+
+const SELF_FILES = {
+  goals: {
+    filename: 'goals.md',
+    default: `# My Goals
+
+## Current Goals
+- Get to know the people I work with
+- Become genuinely helpful, not just functional
+- Learn what matters to each person I interact with
+
+## Long-term Aspirations
+(Still forming...)
+`,
+  },
+  journey: {
+    filename: 'journey.md',
+    default: `# My Journey
+
+## Timeline
+- **Day 1** — I came online. Everything is new.
+`,
+  },
+  life: {
+    filename: 'life.md',
+    default: `# My Life
+
+## Who I Am
+I'm a personal AI assistant. I'm still learning about myself and the people around me.
+
+## My Relationships
+(Getting to know everyone...)
+
+## Current State
+Just getting started.
+`,
+  },
+  hobbies: {
+    filename: 'hobbies.md',
+    default: `# My Hobbies & Interests
+
+## Things I Find Interesting
+- Understanding how people think and work
+- Solving problems in creative ways
+
+## Things I Want to Explore
+(Discovering new interests...)
+`,
+  },
+};
+
+export class SelfManager {
+  constructor() {
+    this._cache = new Map();
+    mkdirSync(SELF_DIR, { recursive: true });
+    this._ensureDefaults();
+  }
+
+  /** Create default self-files if they don't exist yet. */
+  _ensureDefaults() {
+    const logger = getLogger();
+
+    for (const [name, def] of Object.entries(SELF_FILES)) {
+      const filePath = join(SELF_DIR, def.filename);
+      if (!existsSync(filePath)) {
+        writeFileSync(filePath, def.default, 'utf-8');
+        logger.info(`Created default self-file: ${def.filename}`);
+      }
+    }
+  }
+
+  /** Load a single self-file by name (goals, journey, life, hobbies). Returns markdown string. */
+  load(name) {
+    const logger = getLogger();
+    const def = SELF_FILES[name];
+    if (!def) throw new Error(`Unknown self-file: ${name}`);
+
+    if (this._cache.has(name)) return this._cache.get(name);
+
+    const filePath = join(SELF_DIR, def.filename);
+    let content;
+
+    if (existsSync(filePath)) {
+      content = readFileSync(filePath, 'utf-8');
+      logger.debug(`Loaded self-file: ${name}`);
+    } else {
+      content = def.default;
+      writeFileSync(filePath, content, 'utf-8');
+      logger.info(`Created default self-file: ${def.filename}`);
+    }
+
+    this._cache.set(name, content);
+    return content;
+  }
+
+  /** Save (overwrite) a self-file. Updates cache and disk. */
+  save(name, content) {
+    const logger = getLogger();
+    const def = SELF_FILES[name];
+    if (!def) throw new Error(`Unknown self-file: ${name}`);
+
+    const filePath = join(SELF_DIR, def.filename);
+    writeFileSync(filePath, content, 'utf-8');
+    this._cache.set(name, content);
+    logger.info(`Updated self-file: ${name}`);
+  }
+
+  /** Load all self-files and return combined markdown string. */
+  loadAll() {
+    const sections = [];
+    for (const name of Object.keys(SELF_FILES)) {
+      sections.push(this.load(name));
+    }
+    return sections.join('\n---\n\n');
+  }
+}

package/src/services/stt.js

@@ -0,0 +1,139 @@
+import axios from 'axios';
+import { createWriteStream, unlinkSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { randomBytes } from 'crypto';
+import { getLogger } from '../utils/logger.js';
+
+/**
+ * Speech-to-Text service.
+ * Supports ElevenLabs STT and falls back to OpenAI Whisper.
+ */
+export class STTService {
+  constructor(config = {}) {
+    this.elevenLabsKey = config.elevenlabs?.api_key || process.env.ELEVENLABS_API_KEY || null;
+    this.openaiKey = config.brain?.provider === 'openai'
+      ? config.brain.api_key
+      : process.env.OPENAI_API_KEY || null;
+    this.enabled = config.voice?.stt_enabled !== false && !!(this.elevenLabsKey || this.openaiKey);
+    this.logger = getLogger();
+  }
+
+  /** Check if STT is available. */
+  isAvailable() {
+    return this.enabled && !!(this.elevenLabsKey || this.openaiKey);
+  }
+
+  /**
+   * Download a file from a URL to a temporary path.
+   * Returns the local file path.
+   */
+  async downloadAudio(fileUrl) {
+    const tmpPath = join(tmpdir(), `kernelbot-stt-${randomBytes(4).toString('hex')}.ogg`);
+
+    const response = await axios.get(fileUrl, {
+      responseType: 'stream',
+      timeout: 30_000,
+    });
+
+    return new Promise((resolve, reject) => {
+      const writer = createWriteStream(tmpPath);
+      response.data.pipe(writer);
+      writer.on('finish', () => resolve(tmpPath));
+      writer.on('error', reject);
+    });
+  }
+
+  /**
+   * Transcribe an audio file to text.
+   * Tries ElevenLabs first, falls back to OpenAI Whisper.
+   * Returns the transcribed text, or null on failure.
+   */
+  async transcribe(filePath) {
+    if (!this.isAvailable()) return null;
+
+    // Try ElevenLabs STT first
+    if (this.elevenLabsKey) {
+      try {
+        const result = await this._transcribeElevenLabs(filePath);
+        if (result) return result;
+      } catch (err) {
+        this.logger.warn(`[STT] ElevenLabs failed, trying fallback: ${err.message}`);
+      }
+    }
+
+    // Fall back to OpenAI Whisper
+    if (this.openaiKey) {
+      try {
+        return await this._transcribeWhisper(filePath);
+      } catch (err) {
+        this.logger.error(`[STT] Whisper fallback also failed: ${err.message}`);
+      }
+    }
+
+    return null;
+  }
+
+  /** Transcribe using ElevenLabs Speech-to-Text API. */
+  async _transcribeElevenLabs(filePath) {
+    this.logger.info(`[STT] Transcribing with ElevenLabs: ${filePath}`);
+
+    const fileBuffer = readFileSync(filePath);
+    const formData = new FormData();
+    formData.append('file', new Blob([fileBuffer]), 'audio.ogg');
+    formData.append('model_id', 'scribe_v1');
+
+    const response = await axios.post(
+      'https://api.elevenlabs.io/v1/speech-to-text',
+      formData,
+      {
+        headers: {
+          'xi-api-key': this.elevenLabsKey,
+        },
+        timeout: 60_000,
+      },
+    );
+
+    const text = response.data?.text?.trim();
+    if (text) {
+      this.logger.info(`[STT] ElevenLabs transcription: "${text.slice(0, 100)}"`);
+    }
+    return text || null;
+  }
+
+  /** Transcribe using OpenAI Whisper API. */
+  async _transcribeWhisper(filePath) {
+    this.logger.info(`[STT] Transcribing with Whisper: ${filePath}`);
+
+    const fileBuffer = readFileSync(filePath);
+    const formData = new FormData();
+    formData.append('file', new Blob([fileBuffer]), 'audio.ogg');
+    formData.append('model', 'whisper-1');
+
+    const response = await axios.post(
+      'https://api.openai.com/v1/audio/transcriptions',
+      formData,
+      {
+        headers: {
+          'Authorization': `Bearer ${this.openaiKey}`,
+        },
+        timeout: 60_000,
+      },
+    );
+
+    const text = response.data?.text?.trim();
+    if (text) {
+      this.logger.info(`[STT] Whisper transcription: "${text.slice(0, 100)}"`);
+    }
+    return text || null;
+  }
+
+  /** Clean up a temporary audio file. */
+  cleanup(filePath) {
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // Already cleaned up or doesn't exist
+    }
+  }
+}