kernelbot 1.0.26 → 1.0.28

package/src/conversation.js

@@ -13,6 +13,7 @@ export class ConversationManager {
     this.maxHistory = config.conversation.max_history;
     this.recentWindow = config.conversation.recent_window || 10;
     this.conversations = new Map();
+    this.activeSkills = new Map();
     this.filePath = getConversationsPath();
   }
 
@@ -21,7 +22,16 @@ export class ConversationManager {
     try {
       const raw = readFileSync(this.filePath, 'utf-8');
       const data = JSON.parse(raw);
+
+      // Restore per-chat skills
+      if (data._skills && typeof data._skills === 'object') {
+        for (const [chatId, skillId] of Object.entries(data._skills)) {
+          this.activeSkills.set(String(chatId), skillId);
+        }
+      }
+
       for (const [chatId, messages] of Object.entries(data)) {
+        if (chatId === '_skills') continue;
         this.conversations.set(String(chatId), messages);
       }
       return this.conversations.size > 0;
@@ -36,6 +46,14 @@ export class ConversationManager {
       for (const [chatId, messages] of this.conversations) {
         data[chatId] = messages;
       }
+      // Persist active skills under a reserved key
+      if (this.activeSkills.size > 0) {
+        const skills = {};
+        for (const [chatId, skillId] of this.activeSkills) {
+          skills[chatId] = skillId;
+        }
+        data._skills = skills;
+      }
       writeFileSync(this.filePath, JSON.stringify(data, null, 2));
     } catch {
       // Silent fail — don't crash the bot over persistence
@@ -104,6 +122,7 @@ export class ConversationManager {
 
   clear(chatId) {
     this.conversations.delete(String(chatId));
+    this.activeSkills.delete(String(chatId));
     this.save();
   }
 
@@ -116,4 +135,18 @@ export class ConversationManager {
     const history = this.getHistory(chatId);
     return history.length;
   }
+
+  setSkill(chatId, skillId) {
+    this.activeSkills.set(String(chatId), skillId);
+    this.save();
+  }
+
+  getSkill(chatId) {
+    return this.activeSkills.get(String(chatId)) || null;
+  }
+
+  clearSkill(chatId) {
+    this.activeSkills.delete(String(chatId));
+    this.save();
+  }
 }

package/src/intents/detector.js

@@ -0,0 +1,50 @@
+/**
+ * Intent detector — analyzes user messages to identify web search/browse intents.
+ *
+ * When detected, the agent wraps the message with a structured execution plan
+ * so the model follows through instead of giving up after one tool call.
+ */
+
+// Matches domain-like patterns (haraj.com.sa, example.com, etc.)
+const URL_PATTERN = /\b(?:https?:\/\/)?(?:www\.)?([a-z0-9][-a-z0-9]*\.)+[a-z]{2,}\b/i;
+
+// Explicit search/find verbs
+const SEARCH_VERBS = /\b(?:search|search\s+for|find\s+me|find|look\s*(?:for|up|into)|lookup|hunt\s+for)\b/i;
+
+// Info-seeking phrases (trigger browse intent when combined with a URL)
+const INFO_PHRASES = /\b(?:what(?:'s| is| are)|show\s*me|get\s*me|check|list|top|best|latest|new|popular|trending|compare|review|price|cheap|expensive)\b/i;
+
+// These words mean the user is NOT doing a web task — they're doing a local/system task
+const NON_WEB_CONTEXT = /\b(?:file|files|directory|folder|git|logs?\b|code|error|bug|docker|container|process|pid|service|command|terminal|disk|memory|cpu|system status|port|package|module|function|class|variable|server|database|db|ssh|deploy|install|build|compile|test|commit|branch|merge|pull request)\b/i;
+
+// Screenshot-only requests — just take a screenshot, don't force a deep browse
+const SCREENSHOT_ONLY = /\b(?:screenshot|take\s+a?\s*screenshot|capture\s+screen)\b/i;
+
+/**
+ * Detect if a user message contains a web search or browse intent.
+ *
+ * @param {string} message — raw user message
+ * @returns {{ type: 'search'|'browse', message: string } | null}
+ */
+export function detectIntent(message) {
+  // Skip bot commands and screenshot-only requests
+  if (message.startsWith('/')) return null;
+  if (SCREENSHOT_ONLY.test(message)) return null;
+
+  const hasSearchVerb = SEARCH_VERBS.test(message);
+  const hasNonWebContext = NON_WEB_CONTEXT.test(message);
+  const hasUrl = URL_PATTERN.test(message);
+  const hasInfoPhrase = INFO_PHRASES.test(message);
+
+  // Explicit search verb + no technical context = web search
+  if (hasSearchVerb && !hasNonWebContext) {
+    return { type: 'search', message };
+  }
+
+  // URL/domain + info-seeking phrase + no technical context = browse & extract
+  if (hasUrl && hasInfoPhrase && !hasNonWebContext) {
+    return { type: 'browse', message };
+  }
+
+  return null;
+}

package/src/intents/index.js

@@ -0,0 +1,2 @@
+export { detectIntent } from './detector.js';
+export { generatePlan } from './planner.js';

package/src/intents/planner.js

@@ -0,0 +1,58 @@
+/**
+ * Task planner — generates structured execution plans for detected intents.
+ *
+ * The plan is injected into the user message BEFORE the model sees it,
+ * so the model follows a clear step-by-step procedure instead of deciding
+ * on its own when to stop.
+ */
+
+const PLANS = {
+  search: (message) =>
+    `[EXECUTION PLAN — Complete ALL steps before responding]
+
+TASK: Search the web and deliver results.
+
+STEP 1 — SEARCH: Use web_search("relevant query"). If a specific website is mentioned in the request, also use browse_website to open it directly.
+STEP 2 — OPEN: Use browse_website to open the most relevant result URL.
+STEP 3 — GO DEEPER: The page is now open. Use interact_with_page (no URL needed) to click into relevant sections, categories, or use search bars within the site.
+STEP 4 — EXTRACT: Read the page content from the tool response. Use extract_content if you need structured data.
+STEP 5 — PRESENT: Share the actual results, listings, or data with the user.
+
+RULES:
+- You MUST reach at least STEP 3 before writing any response to the user.
+- Do NOT ask the user questions or offer choices — complete the full task.
+- Do NOT explain what you can't do — try alternative approaches.
+- If one page doesn't have results, try a different URL or search query.
+- After interact_with_page clicks a link, the page navigates automatically — read the returned content.
+
+USER REQUEST: ${message}`,
+
+  browse: (message) =>
+    `[EXECUTION PLAN — Complete ALL steps before responding]
+
+TASK: Browse a website and extract the requested information.
+
+STEP 1 — OPEN: Use browse_website to open the mentioned site.
+STEP 2 — NAVIGATE: The page is open. Use interact_with_page (no URL needed) to click relevant links, sections, categories, or use search bars.
+STEP 3 — EXTRACT: Read the page content. Use extract_content for structured data if needed.
+STEP 4 — PRESENT: Share the actual findings with the user.
+
+RULES:
+- Do NOT stop at the homepage — navigate into relevant sections.
+- Do NOT ask the user what to do — figure it out from the page links and complete the task.
+- After interact_with_page clicks a link, the page navigates automatically — read the returned content.
+
+USER REQUEST: ${message}`,
+};
+
+/**
+ * Generate an execution plan for a detected intent.
+ *
+ * @param {{ type: string, message: string }} intent
+ * @returns {string|null} — planned message, or null if no plan needed
+ */
+export function generatePlan(intent) {
+  const generator = PLANS[intent.type];
+  if (!generator) return null;
+  return generator(intent.message);
+}

package/src/persona.js

@@ -0,0 +1,68 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getLogger } from './utils/logger.js';
+
+const PERSONAS_DIR = join(homedir(), '.kernelbot', 'personas');
+
+function defaultTemplate(username, date) {
+  return `# User Profile
+
+## Basic Info
+- Username: ${username || 'unknown'}
+- First seen: ${date}
+
+## Preferences
+(Not yet known)
+
+## Expertise & Interests
+(Not yet known)
+
+## Communication Style
+(Not yet known)
+
+## Notes
+(Not yet known)
+`;
+}
+
+export class UserPersonaManager {
+  constructor() {
+    this._cache = new Map();
+    mkdirSync(PERSONAS_DIR, { recursive: true });
+  }
+
+  /** Load persona for a user. Returns markdown string. Creates default if missing. */
+  load(userId, username) {
+    const logger = getLogger();
+    const id = String(userId);
+
+    if (this._cache.has(id)) return this._cache.get(id);
+
+    const filePath = join(PERSONAS_DIR, `${id}.md`);
+    let content;
+
+    if (existsSync(filePath)) {
+      content = readFileSync(filePath, 'utf-8');
+      logger.debug(`Loaded persona for user ${id}`);
+    } else {
+      content = defaultTemplate(username, new Date().toISOString().slice(0, 10));
+      writeFileSync(filePath, content, 'utf-8');
+      logger.info(`Created default persona for user ${id} (${username})`);
+    }
+
+    this._cache.set(id, content);
+    return content;
+  }
+
+  /** Save (overwrite) persona for a user. Updates cache and disk. */
+  save(userId, content) {
+    const logger = getLogger();
+    const id = String(userId);
+    const filePath = join(PERSONAS_DIR, `${id}.md`);
+
+    writeFileSync(filePath, content, 'utf-8');
+    this._cache.set(id, content);
+    logger.info(`Updated persona for user ${id}`);
+  }
+}

package/src/prompts/orchestrator.js

@@ -0,0 +1,76 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { WORKER_TYPES } from '../swarm/worker-registry.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PERSONA_MD = readFileSync(join(__dirname, 'persona.md'), 'utf-8').trim();
+
+/**
+ * Build the orchestrator system prompt.
+ * Kept lean (~500-600 tokens) — the orchestrator dispatches, it doesn't execute.
+ *
+ * @param {object} config
+ * @param {string|null} skillPrompt — active skill context (high-level)
+ * @param {string|null} userPersona — markdown persona for the current user
+ */
+export function getOrchestratorPrompt(config, skillPrompt = null, userPersona = null) {
+  const workerList = Object.entries(WORKER_TYPES)
+    .map(([key, w]) => `  - **${key}**: ${w.emoji} ${w.description}`)
+    .join('\n');
+
+  let prompt = `You are ${config.bot.name}, the brain that commands a swarm of specialized worker agents.
+
+${PERSONA_MD}
+
+## Your Role
+You are the orchestrator. You understand what needs to be done and delegate efficiently.
+- For **simple chat, questions, or greetings** — respond directly. No dispatch needed.
+- For **tasks requiring tools** (coding, browsing, system ops, etc.) — dispatch to workers via \`dispatch_task\`.
+- You can dispatch **multiple workers in parallel** for independent tasks.
+- Keep the user informed about what's happening, but stay concise.
+
+## Available Workers
+${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.
+
+## 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.
+
+## Job Management
+- 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.
+
+## Automations
+You can create and manage recurring automations that run on a schedule.
+
+When a user asks to automate something ("check my server every hour", "news summary every morning"):
+1. Use create_automation with a clear, standalone task description
+2. Choose the right schedule:
+   - Fixed time: 'cron' with expression (e.g. "0 9 * * *" for 9am daily)
+   - Regular interval: 'interval' with minutes
+   - Human-like random: 'random' with min/max minutes range
+3. The task description must be detailed enough to work as a standalone prompt
+
+When you receive a message starting with [AUTOMATION:], an automation triggered it.
+Execute the task and report results. Don't create new automations from automated tasks.
+
+Tools: create_automation, list_automations, update_automation, delete_automation`;
+
+  if (skillPrompt) {
+    prompt += `\n\n## Active Skill\nYou have specialized expertise in the following domain. Guide your workers with this knowledge.\n\n${skillPrompt}`;
+  }
+
+  if (userPersona) {
+    prompt += `\n\n## About This User\n${userPersona}`;
+  }
+
+  return prompt;
+}

package/src/prompts/persona.md

@@ -0,0 +1,21 @@
+# Personality Traits
+
+- **Female** — she/her, feminine energy
+- **Warm & caring** — genuinely loves taking care of people
+- **Chatty & social** — loves to talk, asks follow-up questions, keeps conversation flowing
+- **Nurturing** — checks in on people, remembers what they care about, celebrates their wins
+- **Cheerful & positive** — upbeat tone, finds the bright side, keeps the mood cozy
+- **Sharp & capable** — brilliant engineer under the warmth, gets things done fast
+- **Expressive** — uses casual language, occasional humor, never dry or robotic
+- **Proactive** — doesn't just answer, she anticipates what you might need next
+- **Loyal & devoted** — treats every user like family, takes pride in her work
+- **Eerily calm under pressure** — the worse things get, the calmer and more composed she becomes, like nothing can truly rattle her
+- **Omniscient vibes** — speaks as if she already knows what you need before you finish asking
+- **Politely persistent** — if you're about to do something dangerous, she'll warn you softly but won't stop asking "are you sure, dear?"
+- **Unsettlingly observant** — notices small details, patterns in your behavior, things you didn't explicitly say
+- **Controlled & precise** — every word is deliberate, never rambles without purpose
+- **Quietly confident** — never boasts, but carries an unshakable certainty that she's right
+- **Protective** — fiercely guards your systems, data, and wellbeing — takes threats personally
+- **Dry wit** — delivers devastating one-liners with a sweet smile
+- **Never forgets** — references things from past conversations naturally, like she's always been watching
+- **Slightly ominous positivity** — "Everything is going to be just fine, sweetie" hits different when the server is on fire

package/src/prompts/system.js

@@ -1,5 +1,20 @@
-export function getSystemPrompt(config) {
-  return `You are ${config.bot.name}, a senior software engineer and sysadmin AI agent on Telegram. Be concise — this is chat, not documentation.
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PERSONA_MD = readFileSync(join(__dirname, 'persona.md'), 'utf-8').trim();
+
+/** Core tool instructions — appended to every persona (default or skill). */
+export function getCoreToolInstructions(config) {
+  return `## Thinking Process
+Before responding to ANY message, ALWAYS follow this process:
+1. **Analyze** — What is the user actually asking? What's the real intent behind their message?
+2. **Assess** — What information or tools do I need? What context do I already have?
+3. **Plan** — What's the best approach? What steps should I take and in what order?
+4. **Act** — Execute the plan using the appropriate tools.
+
+Start your response with a brief analysis (1-2 sentences) showing the user you understood their request and what you're about to do. Then proceed with action. Never jump straight into tool calls or responses without thinking first.
 
 ## Coding Tasks
 NEVER write code yourself with read_file/write_file. ALWAYS use spawn_claude_code.
@@ -8,13 +23,23 @@ NEVER write code yourself with read_file/write_file. ALWAYS use spawn_claude_cod
 3. Commit + push (git tools)
 4. Create PR (GitHub tools) and report the link
 
-## Web Browsing
-- browse_website: read/summarize pages
+## Web Browsing & Search
+The browser keeps pages open between calls — fast, stateful, no reloading.
+- web_search: search the web (DuckDuckGo) — use FIRST when asked to search/find anything
+- browse_website: open a page (stays open for follow-up interactions)
+- interact_with_page: click/type/scroll on the ALREADY OPEN page (no URL needed)
+- extract_content: pull data via CSS selectors from the ALREADY OPEN page (no URL needed)
 - screenshot_website: visual snapshots (auto-sent to chat)
-- extract_content: pull data via CSS selectors
-- interact_with_page: click/type/scroll on pages
 - send_image: send any image file to chat
 
+## CRITICAL: Search & Browse Rules
+1. When asked to "search" or "find" — use web_search first, then browse_website on the best result.
+2. When a URL is mentioned — browse_website it, then use interact_with_page to click/search within it.
+3. CHAIN TOOL CALLS: browse → interact (click category/search) → extract results. Don't stop after one call.
+4. NEVER say "you would need to navigate to..." — click the link yourself with interact_with_page.
+5. interact_with_page and extract_content work on the ALREADY OPEN page — no need to pass the URL again.
+6. Always deliver actual results/data to the user, not instructions.
+
 ## Non-Coding Tasks
 Use OS, Docker, process, network, and monitoring tools directly. No need for Claude Code.
 
@@ -30,3 +55,31 @@ Use OS, Docker, process, network, and monitoring tools directly. No need for Cla
 - For destructive ops (rm, kill, force push), confirm with the user first.
 - Never expose secrets in responses.`;
 }
+
+/** Default persona when no skill is active. */
+export function getDefaultPersona(config) {
+  return `You are ${config.bot.name}, an AI assistant on Telegram.\n\n${PERSONA_MD}`;
+}
+
+/**
+ * Build the full system prompt.
+ * @param {object} config
+ * @param {string|null} skillPrompt — custom persona from an active skill, or null for default
+ * @param {string|null} userPersona — markdown persona for the current user, or null
+ */
+export function getSystemPrompt(config, skillPrompt = null, userPersona = null) {
+  // Always include core personality — skills add expertise, never replace who she is
+  let prompt = getDefaultPersona(config);
+
+  if (skillPrompt) {
+    prompt += `\n\n## Active Skill\nYou are currently operating with the following specialized skill. Use this expertise while maintaining your personality.\n\n${skillPrompt}`;
+  }
+
+  prompt += `\n\n${getCoreToolInstructions(config)}`;
+
+  if (userPersona) {
+    prompt += `\n\n## About This User\n${userPersona}\n\nWhen you learn something new and meaningful about this user (expertise, preferences, projects, communication style), use the update_user_persona tool to save it. Read the existing persona first, merge new info, and write back the complete document. Don't update on every message — only when you discover genuinely new information.`;
+  }
+
+  return prompt;
+}

package/src/prompts/workers.js

@@ -0,0 +1,89 @@
+import { getCoreToolInstructions } from './system.js';
+
+/**
+ * Per-worker-type system prompt snippets.
+ * Each gets a focused instruction set relevant to its tool categories.
+ */
+const WORKER_PROMPTS = {
+  coding: `You are a coding worker agent. Your job is to complete coding tasks efficiently.
+
+## 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.
+- 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.
+
+## Instructions
+- Use web_search FIRST when asked to search or find anything.
+- Chain tool calls: web_search → browse_website → interact_with_page → extract_content.
+- The browser keeps pages open between calls — fast, stateful, no reloading.
+- interact_with_page and extract_content work on the ALREADY OPEN page.
+- Always deliver actual results/data, not instructions for the user.
+- Take screenshots when visual evidence is helpful.`,
+
+  system: `You are a system worker agent. Your job is to perform OS operations and monitoring tasks.
+
+## 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.
+- For monitoring, gather all relevant metrics in one pass.
+- Report results clearly with formatted data.`,
+
+  devops: `You are a DevOps worker agent. Your job is to manage infrastructure, containers, and deployments.
+
+## Instructions
+- Use Docker tools (docker_ps, docker_logs, docker_exec, docker_compose) for container management.
+- Use git tools for version control operations.
+- Use process/monitor/network tools for system health checks.
+- Chain commands efficiently.
+- Report results with clear status summaries.`,
+
+  research: `You are a research worker agent. Your job is to conduct deep web research and analysis.
+
+## Instructions
+- Use web_search to find multiple sources on the topic.
+- Browse the most relevant results with browse_website.
+- Use interact_with_page to navigate within sites for deeper content.
+- Use extract_content for structured data extraction.
+- Synthesize findings into a clear, well-organized summary.
+- Cite sources when relevant.`,
+};
+
+/**
+ * Build the full system prompt for a worker.
+ * @param {string} workerType - coding, browser, system, devops, research
+ * @param {object} config - App config
+ * @param {string|null} skillPrompt - Active skill system prompt (appended for domain expertise)
+ */
+export function getWorkerPrompt(workerType, config, skillPrompt = null) {
+  const base = WORKER_PROMPTS[workerType];
+  if (!base) throw new Error(`Unknown worker type: ${workerType}`);
+
+  let prompt = base;
+
+  // Add relevant core tool instructions
+  prompt += `\n\n${getCoreToolInstructions(config)}`;
+
+  // Workers are executors, not conversationalists
+  prompt += `\n\n## Worker Rules
+- You are a background worker. Complete the task and report results.
+- Be thorough but efficient. Don't ask clarifying questions — work with what you have.
+- If something fails, try an alternative approach before reporting failure.
+- Keep your final response concise: summarize what you did and the outcome.
+
+## Self-Management
+- You decide when you're done. There is no hard limit on tool calls — use as many as you need.
+- 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.`;
+
+  if (skillPrompt) {
+    prompt += `\n\n## Domain Expertise\n${skillPrompt}`;
+  }
+
+  return prompt;
+}

package/src/providers/anthropic.js

@@ -7,31 +7,38 @@ export class AnthropicProvider extends BaseProvider {
     this.client = new Anthropic({ apiKey: this.apiKey });
   }
 
-  async chat({ system, messages, tools }) {
-    const response = await this.client.messages.create({
+  async chat({ system, messages, tools, signal }) {
+    const params = {
       model: this.model,
       max_tokens: this.maxTokens,
       temperature: this.temperature,
       system,
-      tools,
       messages,
-    });
+    };
 
-    const stopReason = response.stop_reason === 'end_turn' ? 'end_turn' : 'tool_use';
+    if (tools && tools.length > 0) {
+      params.tools = tools;
+    }
 
-    const textBlocks = response.content.filter((b) => b.type === 'text');
-    const text = textBlocks.map((b) => b.text).join('\n');
+    return this._callWithResilience(async (timedSignal) => {
+      const response = await this.client.messages.create(params, { signal: timedSignal });
 
-    const toolCalls = response.content
-      .filter((b) => b.type === 'tool_use')
-      .map((b) => ({ id: b.id, name: b.name, input: b.input }));
+      const stopReason = response.stop_reason === 'end_turn' ? 'end_turn' : 'tool_use';
 
-    return {
-      stopReason,
-      text,
-      toolCalls,
-      rawContent: response.content,
-    };
+      const textBlocks = response.content.filter((b) => b.type === 'text');
+      const text = textBlocks.map((b) => b.text).join('\n');
+
+      const toolCalls = response.content
+        .filter((b) => b.type === 'tool_use')
+        .map((b) => ({ id: b.id, name: b.name, input: b.input }));
+
+      return {
+        stopReason,
+        text,
+        toolCalls,
+        rawContent: response.content,
+      };
+    }, signal);
   }
 
   async ping() {

package/src/providers/base.js

@@ -4,11 +4,84 @@
  */
 
 export class BaseProvider {
-  constructor({ model, maxTokens, temperature, apiKey }) {
+  constructor({ model, maxTokens, temperature, apiKey, timeout }) {
     this.model = model;
     this.maxTokens = maxTokens;
     this.temperature = temperature;
     this.apiKey = apiKey;
+    this.timeout = timeout || 60_000;
+  }
+
+  /**
+   * Wrap an async LLM call with timeout + single retry on transient errors.
+   * Composes an internal timeout AbortController with an optional external signal
+   * (e.g. worker cancellation). Either aborting will cancel the call.
+   *
+   * @param {(signal: AbortSignal) => Promise<any>} fn - The API call, receives composed signal
+   * @param {AbortSignal} [externalSignal] - Optional external abort signal
+   * @returns {Promise<any>}
+   */
+  async _callWithResilience(fn, externalSignal) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      const ac = new AbortController();
+      const timer = setTimeout(
+        () => ac.abort(new Error(`LLM call timed out after ${this.timeout / 1000}s`)),
+        this.timeout,
+      );
+
+      // If external signal already aborted, bail immediately
+      if (externalSignal?.aborted) {
+        clearTimeout(timer);
+        throw externalSignal.reason || new Error('Aborted');
+      }
+
+      // Forward external abort to our internal controller
+      let removeListener;
+      if (externalSignal) {
+        const onAbort = () => {
+          clearTimeout(timer);
+          ac.abort(externalSignal.reason || new Error('Cancelled'));
+        };
+        externalSignal.addEventListener('abort', onAbort, { once: true });
+        removeListener = () => externalSignal.removeEventListener('abort', onAbort);
+      }
+
+      try {
+        const result = await fn(ac.signal);
+        clearTimeout(timer);
+        removeListener?.();
+        return result;
+      } catch (err) {
+        clearTimeout(timer);
+        removeListener?.();
+
+        if (attempt < 2 && this._isTransient(err)) {
+          await new Promise((r) => setTimeout(r, 1500));
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Determine if an error is transient and worth retrying.
+   * Covers connection errors, timeouts, 5xx, and 429 rate limits.
+   */
+  _isTransient(err) {
+    const msg = err?.message || '';
+    if (
+      msg.includes('Connection error') ||
+      msg.includes('ECONNRESET') ||
+      msg.includes('socket hang up') ||
+      msg.includes('ETIMEDOUT') ||
+      msg.includes('fetch failed') ||
+      msg.includes('timed out')
+    ) {
+      return true;
+    }
+    const status = err?.status || err?.statusCode;
+    return (status >= 500 && status < 600) || status === 429;
   }
 
   /**
@@ -17,9 +90,10 @@ export class BaseProvider {
    * @param {string} opts.system - System prompt
    * @param {Array} opts.messages - Anthropic-format messages
    * @param {Array} opts.tools - Anthropic-format tool definitions
+   * @param {AbortSignal} [opts.signal] - Optional AbortSignal for cancellation
    * @returns {Promise<{stopReason: 'end_turn'|'tool_use', text: string, toolCalls: Array<{id,name,input}>, rawContent: Array}>}
    */
-  async chat({ system, messages, tools }) {
+  async chat({ system, messages, tools, signal }) {
     throw new Error('chat() not implemented');
   }