@dotsetlabs/dotclaw 1.9.0 → 2.1.0

package/container/agent-runner/src/index.ts

@@ -7,7 +7,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { OpenRouter, stepCountIs } from '@openrouter/sdk';
-import { createTools, ToolCallRecord } from './tools.js';
+import { createTools, discoverMcpTools, ToolCallRecord } from './tools.js';
 import { createIpcHandlers } from './ipc.js';
 import { loadAgentConfig } from './agent-config.js';
 import { OUTPUT_START_MARKER, OUTPUT_END_MARKER, type ContainerInput, type ContainerOutput } from './container-protocol.js';
@@ -27,6 +27,7 @@ import {
   Message
 } from './memory.js';
 import { loadPromptPackWithCanary, formatPromptPack, PromptPack } from './prompt-packs.js';
+import { buildSkillCatalog, formatSkillCatalog, type SkillCatalog } from './skill-loader.js';
 
 type OpenRouterResult = ReturnType<OpenRouter['callModel']>;
 
@@ -40,9 +41,6 @@ const AVAILABLE_GROUPS_PATH = '/workspace/ipc/available_groups.json';
 const GROUP_CLAUDE_PATH = path.join(GROUP_DIR, 'CLAUDE.md');
 const GLOBAL_CLAUDE_PATH = path.join(GLOBAL_DIR, 'CLAUDE.md');
 const CLAUDE_NOTES_MAX_CHARS = 4000;
-const SKILL_NOTES_MAX_FILES = 16;
-const SKILL_NOTES_MAX_CHARS = 3000;
-const SKILL_NOTES_TOTAL_MAX_CHARS = 18_000;
 
 const agentConfig = loadAgentConfig();
 const agent = agentConfig.agent;
@@ -61,10 +59,31 @@ function getCachedOpenRouter(apiKey: string, options: ReturnType<typeof getOpenR
   if (cachedOpenRouter && cachedOpenRouterKey === apiKey && cachedOpenRouterOptions === optionsKey) {
     return cachedOpenRouter;
   }
-  cachedOpenRouter = new OpenRouter({
+  const client = new OpenRouter({
     apiKey,
     ...options
   });
+
+  // The SDK accepts httpReferer/xTitle in the constructor but never injects
+  // them as HTTP headers in the Responses API path (betaResponsesSend).
+  // Wrap callModel to inject them on every request.
+  const { httpReferer, xTitle } = options;
+  if (httpReferer || xTitle) {
+    const extraHeaders: Record<string, string> = {};
+    if (httpReferer) extraHeaders['HTTP-Referer'] = httpReferer;
+    if (xTitle) extraHeaders['X-Title'] = xTitle;
+
+    const originalCallModel = client.callModel.bind(client);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.callModel = (request: any, opts?: any) => {
+      return originalCallModel(request, {
+        ...opts,
+        headers: { ...extraHeaders, ...(opts?.headers as Record<string, string>) }
+      });
+    };
+  }
+
+  cachedOpenRouter = client;
   cachedOpenRouterKey = apiKey;
   cachedOpenRouterOptions = optionsKey;
   return cachedOpenRouter;
@@ -74,168 +93,30 @@ function log(message: string): void {
   console.error(`[agent-runner] ${message}`);
 }
 
-// ── Response extraction pipeline ─────────────────────────────────────
-// OpenRouter SDK v0.3.x returns raw response IDs (gen-*, resp-*, etc.) instead
-// of text for fast reasoning models (GPT-5-mini/nano). Reasoning tokens consume
-// the output budget, leaving nothing for actual text. This multi-layer pipeline
-// works around that:
-//   1. isLikelyResponseId — detect leaked IDs so we never surface them
-//   2. extractTextFromRawResponse — walk raw response fields ourselves
-//   3. getTextWithFallback — try SDK getText(), fall back to raw extraction
-//   4. chatCompletionsFallback — retry via /chat/completions when all else fails
-// Remove this pipeline once the SDK reliably returns text for reasoning models.
-
-const RESPONSE_ID_PREFIXES = ['gen-', 'resp-', 'resp_', 'chatcmpl-', 'msg_'];
-
-function isLikelyResponseId(value: string): boolean {
-  const trimmed = value.trim();
-  if (!trimmed || trimmed.includes(' ') || trimmed.includes('\n')) return false;
-  return RESPONSE_ID_PREFIXES.some(prefix => trimmed.startsWith(prefix));
+function classifyError(err: unknown): 'retryable' | null {
+  const msg = err instanceof Error ? err.message : String(err);
+  const lower = msg.toLowerCase();
+  if (/429|rate.?limit/.test(lower)) return 'retryable';
+  if (/\b5\d{2}\b/.test(msg) || /server error|bad gateway|unavailable/.test(lower)) return 'retryable';
+  if (/timeout|timed out|deadline/.test(lower)) return 'retryable';
+  if (/model.?not.?available|no endpoints|provider error/.test(lower)) return 'retryable';
+  return null;
 }
 
-function isValidText(value: unknown): value is string {
-  return typeof value === 'string' && value.trim().length > 0 && !isLikelyResponseId(value);
-}
-
-function extractTextFromRawResponse(response: unknown): string {
-  if (!response || typeof response !== 'object') return '';
-  const record = response as Record<string, unknown>;
-
-  // 1. SDK-parsed camelCase field
-  if (isValidText(record.outputText)) return record.outputText;
-
-  // 2. Raw API snake_case field
-  if (isValidText(record.output_text)) return record.output_text;
-
-  // 3. Walk response.output[] for message/output_text items
-  if (Array.isArray(record.output)) {
-    const parts: string[] = [];
-    for (const item of record.output) {
-      if (!item || typeof item !== 'object') continue;
-      const typed = item as { type?: string; content?: unknown; text?: string };
-      if (typed.type === 'message' && Array.isArray(typed.content)) {
-        for (const part of typed.content as Array<{ type?: string; text?: string }>) {
-          if (part?.type === 'output_text' && isValidText(part.text)) {
-            parts.push(part.text);
-          }
-        }
-      } else if (typed.type === 'output_text' && isValidText(typed.text)) {
-        parts.push(typed.text);
-      }
-    }
-    const joined = parts.join('');
-    if (joined.trim()) return joined;
-  }
-
-  // 4. OpenAI chat completions compat
-  if (Array.isArray(record.choices) && record.choices.length > 0) {
-    const choice = record.choices[0] as { message?: { content?: unknown } } | null | undefined;
-    if (choice?.message && isValidText(choice.message.content)) {
-      return choice.message.content;
-    }
-  }
-
-  return '';
-}
+// ── Response text extraction ─────────────────────────────────────────
 
-async function getTextWithFallback(result: OpenRouterResult, context: string): Promise<string> {
-  // 1. Try the SDK's proper getText() first — this handles tool execution and
-  //    extracts text from the final response via the SDK's own logic.
+async function getResponseText(result: OpenRouterResult, context: string): Promise<{ text: string; error?: string }> {
   try {
     const text = await result.getText();
-    if (isValidText(text)) {
-      return text;
-    }
-    if (text && isLikelyResponseId(text)) {
-      log(`Ignored response id from getText (${context}): ${String(text).slice(0, 60)}`);
+    if (typeof text === 'string' && text.trim()) {
+      return { text };
     }
   } catch (err) {
-    log(`getText failed (${context}): ${err instanceof Error ? err.message : String(err)}`);
+    const message = err instanceof Error ? err.message : String(err);
+    log(`getText failed (${context}): ${message}`);
+    return { text: '', error: message };
   }
-
-  // 2. Fall back to raw response extraction — walk known fields ourselves
-  try {
-    const response = await result.getResponse();
-    const fallbackText = extractTextFromRawResponse(response);
-    if (fallbackText) {
-      log(`Recovered text from raw response (${context})`);
-      return fallbackText;
-    }
-    const r = response as Record<string, unknown>;
-    const outputLen = Array.isArray(r.output) ? (r.output as unknown[]).length : 0;
-    log(`No text in raw response (${context}): id=${String(r.id ?? 'none').slice(0, 40)} status=${String(r.status ?? '?')} outputs=${outputLen}`);
-  } catch (err) {
-    log(`Raw response extraction failed (${context}): ${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  // 3. Never return a response ID
-  return '';
-}
-
-/**
- * Direct Chat Completions API fallback.
- * When the Responses API returns a gen-ID instead of text (common with fast
- * models like gpt-5-nano/mini via OpenRouter), retry using the standard
- * /chat/completions endpoint which reliably returns text content.
- */
-async function chatCompletionsFallback(params: {
-  model: string;
-  instructions: string;
-  messages: Array<{ role: string; content: string }>;
-  maxOutputTokens: number;
-  temperature: number;
-}): Promise<string> {
-  const apiKey = process.env.OPENROUTER_API_KEY;
-  if (!apiKey) return '';
-
-  const headers: Record<string, string> = {
-    'Authorization': `Bearer ${apiKey}`,
-    'Content-Type': 'application/json'
-  };
-  if (agent.openrouter.siteUrl) {
-    headers['HTTP-Referer'] = agent.openrouter.siteUrl;
-  }
-  if (agent.openrouter.siteName) {
-    headers['X-Title'] = agent.openrouter.siteName;
-  }
-
-  const chatMessages = [
-    { role: 'system', content: params.instructions },
-    ...params.messages
-  ];
-
-  log(`Chat Completions fallback: model=${params.model}, messages=${chatMessages.length}`);
-  const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({
-      model: params.model,
-      messages: chatMessages,
-      max_completion_tokens: params.maxOutputTokens,
-      temperature: params.temperature,
-      reasoning_effort: 'low'
-    }),
-    signal: AbortSignal.timeout(agent.openrouter.timeoutMs)
-  });
-
-  const bodyText = await response.text();
-  if (!response.ok) {
-    log(`Chat Completions fallback HTTP ${response.status}: ${bodyText.slice(0, 300)}`);
-    return '';
-  }
-
-  try {
-    const data = JSON.parse(bodyText);
-    const content = data?.choices?.[0]?.message?.content;
-    if (isValidText(content)) {
-      log(`Chat Completions fallback recovered text (${String(content).length} chars)`);
-      return content;
-    }
-    log(`Chat Completions fallback returned no text: ${JSON.stringify(data).slice(0, 300)}`);
-  } catch (err) {
-    log(`Chat Completions fallback parse error: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  return '';
+  return { text: '' };
 }
 
 function writeOutput(output: ContainerOutput): void {
@@ -351,62 +232,6 @@ function getConfig(config: ReturnType<typeof loadAgentConfig>): MemoryConfig & {
   };
 }
 
-function buildPlannerPrompt(messages: Message[]): { instructions: string; input: string } {
-  const transcript = messages.map(msg => `${msg.role.toUpperCase()}: ${msg.content}`).join('\n\n');
-  const instructions = [
-    'You are a planning module for a personal assistant.',
-    'Given the conversation, produce a concise plan in JSON.',
-    'Return JSON only with keys:',
-    '- steps: array of short action steps',
-    '- tools: array of tool names you expect to use (if any)',
-    '- risks: array of potential pitfalls or missing info',
-    '- questions: array of clarifying questions (if any)',
-    'Keep each array short. Use empty arrays if not needed.'
-  ].join('\n');
-  const input = `Conversation:\n${transcript}`;
-  return { instructions, input };
-}
-
-function parsePlannerResponse(text: string): { steps: string[]; tools: string[]; risks: string[]; questions: string[] } | null {
-  const trimmed = text.trim();
-  let jsonText = trimmed;
-  const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  if (fenceMatch) {
-    jsonText = fenceMatch[1].trim();
-  }
-  try {
-    const parsed = JSON.parse(jsonText) as Record<string, unknown>;
-    const steps = Array.isArray(parsed.steps) ? parsed.steps.filter(item => typeof item === 'string') : [];
-    const tools = Array.isArray(parsed.tools) ? parsed.tools.filter(item => typeof item === 'string') : [];
-    const risks = Array.isArray(parsed.risks) ? parsed.risks.filter(item => typeof item === 'string') : [];
-    const questions = Array.isArray(parsed.questions) ? parsed.questions.filter(item => typeof item === 'string') : [];
-    return { steps, tools, risks, questions };
-  } catch {
-    return null;
-  }
-}
-
-function formatPlanBlock(plan: { steps: string[]; tools: string[]; risks: string[]; questions: string[] }): string {
-  const lines: string[] = ['Planned approach (planner):'];
-  if (plan.steps.length > 0) {
-    lines.push('Steps:');
-    for (const step of plan.steps) lines.push(`- ${step}`);
-  }
-  if (plan.tools.length > 0) {
-    lines.push('Tools:');
-    for (const tool of plan.tools) lines.push(`- ${tool}`);
-  }
-  if (plan.risks.length > 0) {
-    lines.push('Risks:');
-    for (const risk of plan.risks) lines.push(`- ${risk}`);
-  }
-  if (plan.questions.length > 0) {
-    lines.push('Questions:');
-    for (const question of plan.questions) lines.push(`- ${question}`);
-  }
-  return lines.join('\n');
-}
-
 function getOpenRouterOptions(config: ReturnType<typeof loadAgentConfig>) {
   const timeoutMs = config.agent.openrouter.timeoutMs;
   const retryEnabled = config.agent.openrouter.retry;
@@ -469,11 +294,13 @@ function estimateMessagesTokens(messages: Message[], tokensPerChar: number, toke
   return total;
 }
 
+const MEMORY_SUMMARY_MAX_CHARS = 2000;
+
 function buildSystemInstructions(params: {
   assistantName: string;
   groupNotes?: string | null;
   globalNotes?: string | null;
-  skillNotes?: SkillNote[];
+  skillCatalog?: SkillCatalog | null;
   memorySummary: string;
   memoryFacts: string[];
   sessionRecall: string[];
@@ -484,161 +311,74 @@ function buildSystemInstructions(params: {
   toolReliability?: Array<{ name: string; success_rate: number; count: number; avg_duration_ms: number | null }>;
   behaviorConfig?: Record<string, unknown>;
   isScheduledTask: boolean;
-  isBackgroundTask: boolean;
   taskId?: string;
-  isBackgroundJob: boolean;
-  jobId?: string;
   timezone?: string;
   hostPlatform?: string;
-  planBlock?: string;
+  messagingPlatform?: string;
   taskExtractionPack?: PromptPack | null;
   responseQualityPack?: PromptPack | null;
   toolCallingPack?: PromptPack | null;
   toolOutcomePack?: PromptPack | null;
   memoryPolicyPack?: PromptPack | null;
   memoryRecallPack?: PromptPack | null;
+  maxToolSteps?: number;
 }): string {
-  const toolsDoc = [
-    'Tools available (use with care):',
-    '- `Bash`: run shell commands in `/workspace/group`.',
-    '- `Read`, `Write`, `Edit`, `Glob`, `Grep`: filesystem operations within mounted paths.',
-    '- `WebSearch`: Brave Search API (requires `BRAVE_SEARCH_API_KEY`).',
-    '- `WebFetch`: fetch URLs (limit payload sizes).',
-    '- `GitClone`: clone git repositories into the workspace.',
-    '- `NpmInstall`: install npm dependencies in the workspace.',
-    '- `mcp__dotclaw__send_message`: send Telegram messages.',
-    '- `mcp__dotclaw__send_file`: send a file/document.',
-    '- `mcp__dotclaw__send_photo`: send a photo with compression.',
-    '- `mcp__dotclaw__send_voice`: send a voice message (.ogg format).',
-    '- `mcp__dotclaw__send_audio`: send an audio file (mp3, m4a, etc.).',
-    '- `mcp__dotclaw__send_location`: send a map pin (latitude/longitude).',
-    '- `mcp__dotclaw__send_contact`: send a contact card (phone + name).',
-    '- `mcp__dotclaw__send_poll`: create a Telegram poll.',
-    '- `mcp__dotclaw__send_buttons`: send a message with inline keyboard buttons.',
-    '- `mcp__dotclaw__edit_message`: edit a previously sent message.',
-    '- `mcp__dotclaw__delete_message`: delete a message.',
-    '- `mcp__dotclaw__download_url`: download a URL to the workspace as a file.',
-    '- To send media from the web: (1) download with `mcp__dotclaw__download_url` or `curl`/`wget` via Bash, (2) send with `mcp__dotclaw__send_photo`/`send_file`/`send_voice`/`send_audio`. This is a quick foreground task — do NOT use spawn_job for it.',
-    '- Users may send photos, documents, voice messages, and videos. These are downloaded to `/workspace/group/inbox/` and referenced as `<attachment>` tags in messages. Process them with Read/Bash/Python tools. Use ffmpeg for audio/video transcoding (e.g. voice messages must be .ogg Opus for send_voice).',
-    '- GitHub CLI (`gh`) is available. If GH_TOKEN is set, you can clone repos, create PRs, manage issues, etc. Use `gh auth status` to check authentication.',
-    '- `mcp__dotclaw__schedule_task`: schedule tasks (set `timezone` for locale-specific schedules).',
-    '- `mcp__dotclaw__run_task`: run a scheduled task immediately.',
-    '- `mcp__dotclaw__list_tasks`, `mcp__dotclaw__pause_task`, `mcp__dotclaw__resume_task`, `mcp__dotclaw__cancel_task`.',
-    '- `mcp__dotclaw__update_task`: update a task (state, prompt, schedule, status).',
-    '- `mcp__dotclaw__spawn_job`: start a background job.',
-    '- `mcp__dotclaw__job_status`, `mcp__dotclaw__list_jobs`, `mcp__dotclaw__cancel_job`.',
-    '- `mcp__dotclaw__job_update`: log job progress or notify the user.',
-    'Rule: Use `mcp__dotclaw__spawn_job` ONLY for tasks that genuinely take more than ~2 minutes (cloning large repos, multi-page web research, complex coding projects). Everything else — downloading files, sending media, quick lookups, data analysis, format conversions, chart generation, scheduling reminders, web searches — should be done directly in the foreground. When in doubt, do it in the foreground.',
-    'When you DO spawn a background job, keep your reply to the user minimal — e.g. "Working on it, I\'ll send the results when done." Do not include the job ID, bullet-point plans, next steps, or status monitoring offers. The user will receive the result automatically.',
-    '- `mcp__dotclaw__register_group`: manage chat registrations.',
-    '- `mcp__dotclaw__remove_group`, `mcp__dotclaw__list_groups`: manage registered groups.',
-    '- `mcp__dotclaw__set_model`: change the active model.',
-    '- `mcp__dotclaw__memory_upsert`: store durable memories.',
-    '- `mcp__dotclaw__memory_search`, `mcp__dotclaw__memory_list`, `mcp__dotclaw__memory_forget`, `mcp__dotclaw__memory_stats`.',
-    '- `plugin__*`: dynamically loaded plugin tools (if present and allowed by policy).'
-  ].join('\n');
-  const browserAutomation = [
-    'Browser automation (via Bash):',
-    '- Use `agent-browser open <url>` then `agent-browser snapshot -i`.',
-    '- Interact with refs using `agent-browser click @e1`, `fill @e2 "text"`.',
-    '- Capture evidence with `agent-browser screenshot`.'
+  const toolGuidance = [
+    'Key tool rules:',
+    '- User attachments arrive in /workspace/group/inbox/ (see <attachment> tags). Process with Read/Bash/Python.',
+    '- To send media from the web: download_url → send_photo/send_file/send_audio.',
+    '- Charts/plots: matplotlib → savefig → send_photo. Graphviz → dot -Tpng → send_photo.',
+    '- Voice messages are auto-transcribed (<transcript> in <attachment>). Reply with normal text — the host auto-converts to voice.',
+    '- GitHub CLI (`gh`) is available if GH_TOKEN is set.',
+    '- plugin__* and mcp_ext__* tools may be available if configured.'
   ].join('\n');
 
-  const commonWorkflows = [
-    'Common workflows (do all of these in the foreground — act immediately, never spawn_job):',
-    '',
-    'Sending media from the web:',
-    '  download_url (or curl/wget) → send_photo / send_file / send_audio.',
-    '',
-    'Charts & plots:',
-    '  Python: matplotlib/pandas .plot() → plt.savefig("/workspace/group/chart.png") → send_photo.',
-    '  Graphviz: write .dot file → Bash `dot -Tpng diagram.dot -o diagram.png` → send_photo.',
-    '  Always save to a file and send — never try to "display" inline.',
-    '',
-    'Processing user attachments:',
-    '  Files arrive in /workspace/group/inbox/. The path is in the <attachment> tag.',
-    '  Spreadsheets (.xlsx/.csv): `pd.read_excel()` or `pd.read_csv()` → analyze → respond.',
-    '  JSON: Read tool or `json.load()` → analyze → respond.',
-    '  Images: Python Pillow for processing, or describe what you see if relevant.',
-    '  PDFs: Python `PyPDF2` (install at runtime if needed), or `pdftotext` via Bash.',
-    '  Archives (.zip/.tar): `unzip -l` or `tar -tf` to list, extract as needed.',
-    '  Unknown types: use `file` command to identify, then process accordingly.',
-    '',
-    'Creating & delivering files:',
-    '  When the user asks you to create a file (report, CSV, spreadsheet, script, etc.):',
-    '  Write/Python to create the file → send_file to deliver it. Do not paste large file content as a message.',
-    '  For Excel: `openpyxl` or `pd.to_excel()`. For CSV: `pd.to_csv()` or Write tool.',
-    '',
-    'Format conversions:',
-    '  Images: Python Pillow `Image.open().save("out.png")` → send_file.',
-    '  Audio/Video: `ffmpeg -i input.ext output.ext` via Bash → send_file / send_audio.',
-    '  Documents: use appropriate Python libraries or CLI tools → send_file.',
-    '',
-    'Voice messages:',
-    '  Received: arrives as .ogg in inbox. No built-in speech-to-text — acknowledge this to the user.',
-    '  Sending: create/obtain audio → `ffmpeg -i input.mp3 -c:a libopus output.ogg` → send_voice.',
-    '',
-    'Quick lookups (one tool call, immediate response):',
-    '  Time zones: `python3 -c "from datetime import datetime; from zoneinfo import ZoneInfo; ..."`',
-    '  Math/conversions: Python one-liner.',
-    '  Unit conversions, currency, percentages: Python one-liner.',
-    '',
-    'Web research:',
-    '  Simple question: WebSearch → summarize in send_message.',
-    '  Summarize a URL: WebFetch → summarize in send_message.',
-    '  Deep research (many sources): this is the one case that may warrant spawn_job.',
-    '',
-    'Reminders & scheduling:',
-    '  "Remind me at 5pm": one schedule_task call with a cron expression. Done.',
-    '  "Every Monday at 9am": one schedule_task call with cron. Done.',
-    '  Do not overthink scheduling — it is a single tool call.',
-    '',
-    'Diagrams & visualizations:',
-    '  Flowcharts/graphs: write Graphviz .dot → `dot -Tpng` → send_photo.',
-    '  Data visualizations: matplotlib/pandas → savefig → send_photo.',
-    '  Tables: use `tabulate` for markdown/ASCII tables in messages, or create an image for complex tables.'
-  ].join('\n');
+  const browserAutomation = agentConfig.agent.browser.enabled ? [
+    'Browser Tool: actions: navigate, snapshot, click, fill, screenshot, extract, evaluate, close.',
+    'Use snapshot with interactive=true for clickable refs (@e1, @e2). Screenshots → /workspace/group/screenshots/.'
+  ].join('\n') : '';
+
+  const hasAnyMemory = params.memorySummary || params.memoryFacts.length > 0 ||
+    params.longTermRecall.length > 0 || params.userProfile;
 
-  const memorySummary = params.memorySummary ? params.memorySummary : 'None yet.';
+  const memorySummary = params.memorySummary
+    ? params.memorySummary.slice(0, MEMORY_SUMMARY_MAX_CHARS)
+    : '';
   const memoryFacts = params.memoryFacts.length > 0
     ? params.memoryFacts.map(fact => `- ${fact}`).join('\n')
-    : 'None yet.';
+    : '';
   const sessionRecall = params.sessionRecall.length > 0
     ? params.sessionRecall.map(item => `- ${item}`).join('\n')
-    : 'None.';
-
+    : '';
   const longTermRecall = params.longTermRecall.length > 0
     ? params.longTermRecall.map(item => `- ${item}`).join('\n')
-    : 'None.';
-
-  const userProfile = params.userProfile
-    ? params.userProfile
-    : 'None.';
-
+    : '';
+  const userProfile = params.userProfile || '';
   const memoryStats = params.memoryStats
     ? `Total: ${params.memoryStats.total}, User: ${params.memoryStats.user}, Group: ${params.memoryStats.group}, Global: ${params.memoryStats.global}`
-    : 'Unknown.';
+    : '';
 
   const availableGroups = params.availableGroups && params.availableGroups.length > 0
     ? params.availableGroups
       .map(group => `- ${group.name} (chat ${group.jid}, last: ${group.lastActivity})`)
       .join('\n')
-    : 'None.';
+    : '';
 
   const groupNotes = params.groupNotes ? `Group notes:\n${params.groupNotes}` : '';
   const globalNotes = params.globalNotes ? `Global notes:\n${params.globalNotes}` : '';
-  const skillNotes = formatSkillNotes(params.skillNotes || []);
+  const skillNotes = params.skillCatalog ? formatSkillCatalog(params.skillCatalog) : '';
 
   const toolReliability = params.toolReliability && params.toolReliability.length > 0
     ? params.toolReliability
-      .sort((a, b) => b.success_rate - a.success_rate)
+      .sort((a, b) => a.success_rate - b.success_rate)
+      .slice(0, 20)
       .map(tool => {
         const pct = `${Math.round(tool.success_rate * 100)}%`;
         const avg = Number.isFinite(tool.avg_duration_ms) ? `${Math.round(tool.avg_duration_ms!)}ms` : 'n/a';
         return `- ${tool.name}: success ${pct} over ${tool.count} calls (avg ${avg})`;
       })
       .join('\n')
-    : 'No recent tool reliability data.';
+    : '';
 
   const behaviorNotes: string[] = [];
   const responseStyle = typeof params.behaviorConfig?.response_style === 'string'
@@ -677,64 +417,88 @@ function buildSystemInstructions(params: {
   const scheduledNote = params.isScheduledTask
     ? `You are running as a scheduled task${params.taskId ? ` (task id: ${params.taskId})` : ''}. If you need to communicate, use \`mcp__dotclaw__send_message\`.`
     : '';
-  const backgroundNote = params.isBackgroundTask
-    ? 'You are running in the background for a user request. Focus on completing the task and return a complete response without asking follow-up questions unless strictly necessary.'
-    : '';
-  const jobNote = params.isBackgroundJob
-    ? `You are running as a background job${params.jobId ? ` (job id: ${params.jobId})` : ''}. Complete the task silently and return the result. Do NOT call \`mcp__dotclaw__job_update\` for routine progress — only for critical blockers or required user decisions. Do NOT send messages to the chat about your progress. Just do the work and return the final result. The system will deliver your result to the user automatically.`
-    : '';
-  const jobArtifactsNote = params.isBackgroundJob && params.jobId
-    ? `Job artifacts directory: /workspace/group/jobs/${params.jobId}`
-    : '';
 
   const fmtPack = (label: string, pack: PromptPack | null | undefined) =>
     pack ? formatPromptPack({ label, pack, maxDemos: PROMPT_PACKS_MAX_DEMOS, maxChars: PROMPT_PACKS_MAX_CHARS }) : '';
 
-  const taskExtractionBlock = fmtPack('Task Extraction Guidelines', params.taskExtractionPack);
-  const responseQualityBlock = fmtPack('Response Quality Guidelines', params.responseQualityPack);
-  const toolCallingBlock = fmtPack('Tool Calling Guidelines', params.toolCallingPack);
-  const toolOutcomeBlock = fmtPack('Tool Outcome Guidelines', params.toolOutcomePack);
-  const memoryPolicyBlock = fmtPack('Memory Policy Guidelines', params.memoryPolicyPack);
-  const memoryRecallBlock = fmtPack('Memory Recall Guidelines', params.memoryRecallPack);
+  const PROMPT_PACKS_TOTAL_BUDGET = PROMPT_PACKS_MAX_CHARS * 3;
+  const allPackBlocks: string[] = [];
+  {
+    const packEntries: Array<[string, PromptPack | null | undefined]> = [
+      ['Tool Calling Guidelines', params.toolCallingPack],
+      ['Tool Outcome Guidelines', params.toolOutcomePack],
+      ['Task Extraction Guidelines', params.taskExtractionPack],
+      ['Response Quality Guidelines', params.responseQualityPack],
+      ['Memory Policy Guidelines', params.memoryPolicyPack],
+      ['Memory Recall Guidelines', params.memoryRecallPack],
+    ];
+    let totalChars = 0;
+    for (const [label, pack] of packEntries) {
+      const block = fmtPack(label, pack);
+      if (!block) continue;
+      if (totalChars + block.length > PROMPT_PACKS_TOTAL_BUDGET) break;
+      allPackBlocks.push(block);
+      totalChars += block.length;
+    }
+  }
+  const taskExtractionBlock = allPackBlocks.find(b => b.includes('Task Extraction')) || '';
+  const responseQualityBlock = allPackBlocks.find(b => b.includes('Response Quality')) || '';
+  const toolCallingBlock = allPackBlocks.find(b => b.includes('Tool Calling')) || '';
+  const toolOutcomeBlock = allPackBlocks.find(b => b.includes('Tool Outcome')) || '';
+  const memoryPolicyBlock = allPackBlocks.find(b => b.includes('Memory Policy')) || '';
+  const memoryRecallBlock = allPackBlocks.find(b => b.includes('Memory Recall')) || '';
+
+  const memorySections: string[] = [];
+  {
+    if (hasAnyMemory) {
+      if (memorySummary) {
+        memorySections.push('Long-term memory summary:', memorySummary);
+      }
+      if (memoryFacts) {
+        memorySections.push('Long-term facts:', memoryFacts);
+      }
+      if (userProfile) {
+        memorySections.push('User profile (if available):', userProfile);
+      }
+      if (longTermRecall) {
+        memorySections.push('What you remember about the user (long-term):', longTermRecall);
+      }
+      if (memoryStats) {
+        memorySections.push('Memory stats:', memoryStats);
+      }
+    } else {
+      memorySections.push('No long-term memory available yet.');
+    }
+  }
+
+  // Session recall is always included (local context from current conversation)
+  if (sessionRecall) {
+    memorySections.push('Recent conversation context:', sessionRecall);
+  }
 
   return [
-    `You are ${params.assistantName}, a personal assistant running inside DotClaw.`,
+    `You are ${params.assistantName}, a personal assistant running inside DotClaw.${params.messagingPlatform ? ` You are currently connected via ${params.messagingPlatform}.` : ''}`,
     hostPlatformNote,
     scheduledNote,
-    backgroundNote,
-    jobNote,
-    jobArtifactsNote,
-    toolsDoc,
+    toolGuidance,
     browserAutomation,
-    commonWorkflows,
     groupNotes,
     globalNotes,
     skillNotes,
     timezoneNote,
-    params.planBlock || '',
     toolCallingBlock,
     toolOutcomeBlock,
     taskExtractionBlock,
     responseQualityBlock,
     memoryPolicyBlock,
     memoryRecallBlock,
-    'Long-term memory summary:',
-    memorySummary,
-    'Long-term facts:',
-    memoryFacts,
-    'User profile (if available):',
-    userProfile,
-    'What you remember about the user (long-term):',
-    longTermRecall,
-    'Recent conversation context:',
-    sessionRecall,
-    'Memory stats:',
-    memoryStats,
-    'Available groups (main group only):',
-    availableGroups,
-    'Tool reliability (recent):',
-    toolReliability,
+    ...memorySections,
+    availableGroups ? `Available groups (main group only):\n${availableGroups}` : '',
+    toolReliability ? `Tool reliability (recent):\n${toolReliability}` : '',
     behaviorNotes.length > 0 ? `Behavior notes:\n${behaviorNotes.join('\n')}` : '',
+    params.maxToolSteps
+      ? `You have a budget of ${params.maxToolSteps} tool steps per request. If a task is large, break your work into phases and always finish with a text summary of what you accomplished — never end on a tool call without a response.`
+      : '',
     'Be concise and helpful. When you use tools, summarize what happened rather than dumping raw output.'
   ].filter(Boolean).join('\n\n');
 }
@@ -770,122 +534,6 @@ function loadClaudeNotes(): { group: string | null; global: string | null } {
   };
 }
 
-export type SkillNote = {
-  scope: 'group' | 'global';
-  path: string;
-  content: string;
-};
-
-function collectSkillFiles(rootDir: string, maxFiles: number): string[] {
-  const files: string[] = [];
-  const seen = new Set<string>();
-  const addFile = (filePath: string) => {
-    const normalized = path.resolve(filePath);
-    if (seen.has(normalized)) return;
-    if (!fs.existsSync(normalized)) return;
-    let stat: fs.Stats;
-    try {
-      stat = fs.statSync(normalized);
-    } catch {
-      return;
-    }
-    if (!stat.isFile()) return;
-    if (!normalized.toLowerCase().endsWith('.md')) return;
-    seen.add(normalized);
-    files.push(normalized);
-  };
-
-  addFile(path.join(rootDir, 'SKILL.md'));
-
-  const skillsDir = path.join(rootDir, 'skills');
-  if (fs.existsSync(skillsDir)) {
-    const stack = [skillsDir];
-    while (stack.length > 0 && files.length < maxFiles) {
-      const current = stack.pop();
-      if (!current) continue;
-      let entries: fs.Dirent[];
-      try {
-        entries = fs.readdirSync(current, { withFileTypes: true });
-      } catch {
-        continue;
-      }
-      entries.sort((a, b) => a.name.localeCompare(b.name));
-      for (const entry of entries) {
-        const nextPath = path.join(current, entry.name);
-        if (entry.isSymbolicLink()) continue;
-        if (entry.isDirectory()) {
-          stack.push(nextPath);
-          continue;
-        }
-        if (entry.isFile()) {
-          addFile(nextPath);
-        }
-        if (files.length >= maxFiles) break;
-      }
-    }
-  }
-
-  files.sort((a, b) => a.localeCompare(b));
-  return files.slice(0, maxFiles);
-}
-
-export function loadSkillNotesFromRoots(params: {
-  groupDir: string;
-  globalDir: string;
-  maxFiles?: number;
-  maxCharsPerFile?: number;
-  maxTotalChars?: number;
-}): SkillNote[] {
-  const maxFiles = Number.isFinite(params.maxFiles) ? Math.max(1, Math.floor(params.maxFiles!)) : SKILL_NOTES_MAX_FILES;
-  const maxCharsPerFile = Number.isFinite(params.maxCharsPerFile)
-    ? Math.max(200, Math.floor(params.maxCharsPerFile!))
-    : SKILL_NOTES_MAX_CHARS;
-  const maxTotalChars = Number.isFinite(params.maxTotalChars)
-    ? Math.max(maxCharsPerFile, Math.floor(params.maxTotalChars!))
-    : SKILL_NOTES_TOTAL_MAX_CHARS;
-
-  const notes: SkillNote[] = [];
-  let consumedChars = 0;
-
-  const appendScopeNotes = (scope: 'group' | 'global', rootDir: string) => {
-    const skillFiles = collectSkillFiles(rootDir, maxFiles);
-    for (const filePath of skillFiles) {
-      if (notes.length >= maxFiles) break;
-      if (consumedChars >= maxTotalChars) break;
-      const content = readTextFileLimited(filePath, maxCharsPerFile);
-      if (!content) continue;
-      const remaining = maxTotalChars - consumedChars;
-      const truncated = content.length > remaining
-        ? `${content.slice(0, remaining)}\n\n[Truncated for total skill budget]`
-        : content;
-      const relativePath = path.relative(rootDir, filePath).split(path.sep).join('/');
-      notes.push({
-        scope,
-        path: relativePath || path.basename(filePath),
-        content: truncated
-      });
-      consumedChars += truncated.length;
-      if (consumedChars >= maxTotalChars) break;
-    }
-  };
-
-  appendScopeNotes('group', params.groupDir);
-  appendScopeNotes('global', params.globalDir);
-  return notes;
-}
-
-function formatSkillNotes(notes: SkillNote[]): string {
-  if (!notes || notes.length === 0) return '';
-  const lines: string[] = [
-    'Skill instructions (loaded from SKILL.md / skills/*.md):',
-    'When a task matches a skill, follow that skill workflow first and keep output concise.'
-  ];
-  for (const note of notes) {
-    lines.push(`[${note.scope}] ${note.path}`);
-    lines.push(note.content);
-  }
-  return lines.join('\n\n');
-}
 
 function extractQueryFromPrompt(prompt: string): string {
   if (!prompt) return '';
@@ -906,6 +554,47 @@ function decodeXml(value: string): string {
     .replace(/&amp;/g, '&');
 }
 
+// ── Image/Vision support ──────────────────────────────────────────────
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5MB per image
+const MAX_TOTAL_IMAGE_BYTES = 20 * 1024 * 1024; // 20MB total across all images
+const IMAGE_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+
+function loadImageAttachments(attachments?: ContainerInput['attachments']): Array<{
+  type: 'image_url';
+  image_url: { url: string };
+}> {
+  if (!attachments) return [];
+  const images: Array<{ type: 'image_url'; image_url: { url: string } }> = [];
+  let totalBytes = 0;
+  for (const att of attachments) {
+    if (att.type !== 'photo') continue;
+    const mime = att.mime_type || 'image/jpeg';
+    if (!IMAGE_MIME_TYPES.has(mime)) continue;
+    try {
+      const stat = fs.statSync(att.path);
+      if (stat.size > MAX_IMAGE_BYTES) {
+        log(`Skipping image ${att.path}: ${stat.size} bytes exceeds ${MAX_IMAGE_BYTES}`);
+        continue;
+      }
+      if (totalBytes + stat.size > MAX_TOTAL_IMAGE_BYTES) {
+        log(`Skipping image ${att.path}: cumulative size would exceed ${MAX_TOTAL_IMAGE_BYTES}`);
+        break;
+      }
+      const data = fs.readFileSync(att.path);
+      totalBytes += data.length;
+      const b64 = data.toString('base64');
+      images.push({
+        type: 'image_url',
+        image_url: { url: `data:${mime};base64,${b64}` }
+      });
+    } catch (err) {
+      log(`Failed to load image ${att.path}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return images;
+}
+
 function messagesToOpenRouter(messages: Message[]) {
   return messages.map(message => ({
     role: message.role,
@@ -948,7 +637,7 @@ async function updateMemorySummary(params: {
     temperature: 0.1,
     reasoning: { effort: 'low' as const }
   });
-  const text = await getTextWithFallback(result, 'summary');
+  const { text } = await getResponseText(result, 'summary');
   return parseSummaryResponse(text);
 }
 
@@ -1022,122 +711,6 @@ function parseMemoryExtraction(text: string): Array<Record<string, unknown>> {
   }
 }
 
-type ResponseValidation = {
-  verdict: 'pass' | 'fail';
-  issues: string[];
-  missing: string[];
-};
-
-function buildResponseValidationPrompt(params: { userPrompt: string; response: string }): { instructions: string; input: string } {
-  const instructions = [
-    'You are a strict response quality checker.',
-    'Given a user request and an assistant response, decide if the response fully addresses the request.',
-    'Fail if the response is empty, generic, deflects, promises work without results, or ignores any explicit questions.',
-    'Pass only if the response directly answers all parts with concrete, relevant content.',
-    'Return JSON only with keys: verdict ("pass"|"fail"), issues (array of strings), missing (array of strings).'
-  ].join('\n');
-
-  const input = [
-    'User request:',
-    params.userPrompt,
-    '',
-    'Assistant response:',
-    params.response
-  ].join('\n');
-
-  return { instructions, input };
-}
-
-function parseResponseValidation(text: string): ResponseValidation | null {
-  const trimmed = text.trim();
-  let jsonText = trimmed;
-  const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  if (fenceMatch) {
-    jsonText = fenceMatch[1].trim();
-  }
-  try {
-    const parsed = JSON.parse(jsonText);
-    const verdict = parsed?.verdict;
-    if (verdict !== 'pass' && verdict !== 'fail') return null;
-    const issues = Array.isArray(parsed?.issues)
-      ? parsed.issues.filter((issue: unknown) => typeof issue === 'string')
-      : [];
-    const missing = Array.isArray(parsed?.missing)
-      ? parsed.missing.filter((item: unknown) => typeof item === 'string')
-      : [];
-    return { verdict, issues, missing };
-  } catch {
-    return null;
-  }
-}
-
-async function validateResponseQuality(params: {
-  openrouter: OpenRouter;
-  model: string;
-  userPrompt: string;
-  response: string;
-  maxOutputTokens: number;
-  temperature: number;
-}): Promise<ResponseValidation | null> {
-  const prompt = buildResponseValidationPrompt({
-    userPrompt: params.userPrompt,
-    response: params.response
-  });
-  const result = await params.openrouter.callModel({
-    model: params.model,
-    instructions: prompt.instructions,
-    input: prompt.input,
-    maxOutputTokens: params.maxOutputTokens,
-    temperature: params.temperature,
-    reasoning: { effort: 'low' as const }
-  });
-  const text = await getTextWithFallback(result, 'response_validation');
-  return parseResponseValidation(text);
-}
-
-function buildRetryGuidance(validation: ResponseValidation | null): string {
-  const issues = validation?.issues || [];
-  const missing = validation?.missing || [];
-  const points = [...issues, ...missing].filter(Boolean).slice(0, 8);
-  const details = points.length > 0
-    ? points.map(item => `- ${item}`).join('\n')
-    : '- The previous response did not fully address the request.';
-  return [
-    'IMPORTANT: Your previous response did not fully answer the user request.',
-    'Provide a direct, complete answer now. Do not mention this retry.',
-    'Issues to fix:',
-    details
-  ].join('\n');
-}
-
-function buildPlannerTrigger(pattern: string | undefined): RegExp | null {
-  if (!pattern) return null;
-  try {
-    return new RegExp(pattern, 'i');
-  } catch {
-    return null;
-  }
-}
-
-function shouldRunPlanner(params: {
-  enabled: boolean;
-  mode: string;
-  prompt: string;
-  tokensPerChar: number;
-  minTokens: number;
-  trigger: RegExp | null;
-}): boolean {
-  if (!params.enabled) return false;
-  const mode = params.mode.toLowerCase();
-  if (mode === 'always') return true;
-  if (mode === 'off') return false;
-
-  const estimatedTokens = estimateTokensForModel(params.prompt, params.tokensPerChar);
-  if (params.minTokens > 0 && estimatedTokens >= params.minTokens) return true;
-  if (params.trigger && params.trigger.test(params.prompt)) return true;
-  return false;
-}
-
 export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutput> {
   log(`Received input for group: ${input.groupFolder}`);
 
@@ -1161,7 +734,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     config.compactionTriggerTokens = Math.max(1000, Math.min(config.compactionTriggerTokens, compactionTarget));
   }
   if (input.modelMaxOutputTokens && Number.isFinite(input.modelMaxOutputTokens)) {
-    config.maxOutputTokens = Math.min(config.maxOutputTokens, input.modelMaxOutputTokens);
+    config.maxOutputTokens = input.modelMaxOutputTokens;
   }
   if (input.modelTemperature && Number.isFinite(input.modelTemperature)) {
     config.temperature = input.modelTemperature;
@@ -1170,46 +743,29 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
   const maxToolSteps = Number.isFinite(input.maxToolSteps)
     ? Math.max(1, Math.floor(input.maxToolSteps as number))
     : agent.tools.maxToolSteps;
-  const memoryExtractionEnabled = agent.memory.extraction.enabled && !input.disableMemoryExtraction;
+  const memoryExtractionEnabled = agent.memory.extraction.enabled;
   const isDaemon = process.env.DOTCLAW_DAEMON === '1';
-  const memoryExtractionAsync = agent.memory.extraction.async;
   const memoryExtractionMaxMessages = agent.memory.extraction.maxMessages;
   const memoryExtractionMaxOutputTokens = agent.memory.extraction.maxOutputTokens;
   const memoryExtractScheduled = agent.memory.extractScheduled;
   const memoryArchiveSync = agent.memory.archiveSync;
-  const plannerEnabled = agent.planner.enabled && !input.disablePlanner;
-  const plannerMode = String(agent.planner.mode || 'auto').toLowerCase();
-  const plannerMinTokens = agent.planner.minTokens;
-  const plannerTrigger = buildPlannerTrigger(agent.planner.triggerRegex);
-  const plannerModel = agent.models.planner;
-  const plannerMaxOutputTokens = agent.planner.maxOutputTokens;
-  const plannerTemperature = agent.planner.temperature;
-  const responseValidateEnabled = agent.responseValidation.enabled && !input.disableResponseValidation;
-  const responseValidateModel = agent.models.responseValidation;
-  const responseValidateMaxOutputTokens = agent.responseValidation.maxOutputTokens;
-  const responseValidateTemperature = agent.responseValidation.temperature;
-  const responseValidateMaxRetries = Number.isFinite(input.responseValidationMaxRetries)
-    ? Math.max(0, Math.floor(input.responseValidationMaxRetries as number))
-    : agent.responseValidation.maxRetries;
-  const responseValidateAllowToolCalls = agent.responseValidation.allowToolCalls;
-  const responseValidateMinPromptTokens = agent.responseValidation.minPromptTokens || 0;
-  const responseValidateMinResponseTokens = agent.responseValidation.minResponseTokens || 0;
   const maxContextMessageTokens = agent.context.maxContextMessageTokens;
 
   const openrouter = getCachedOpenRouter(apiKey, openrouterOptions);
   const tokenEstimate = resolveTokenEstimate(input, agentConfig);
   const availableGroups = loadAvailableGroups();
   const claudeNotes = loadClaudeNotes();
-  const skillNotes = loadSkillNotesFromRoots({
+  const skillCatalog = buildSkillCatalog({
     groupDir: GROUP_DIR,
-    globalDir: GLOBAL_DIR
+    globalDir: GLOBAL_DIR,
+    maxSkills: agent.skills.maxSkills
   });
 
   const { ctx: sessionCtx, isNew } = createSessionContext(SESSION_ROOT, input.sessionId);
   const toolCalls: ToolCallRecord[] = [];
   let memoryItemsUpserted = 0;
   let memoryItemsExtracted = 0;
-  const timings: { planner_ms?: number; response_validation_ms?: number; memory_extraction_ms?: number; tool_ms?: number } = {};
+  const timings: { memory_extraction_ms?: number; tool_ms?: number } = {};
   const ipc = createIpcHandlers({
     chatJid: input.chatJid,
     groupFolder: input.groupFolder,
@@ -1223,13 +779,39 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     onToolCall: (call) => {
       toolCalls.push(call);
     },
-    policy: input.toolPolicy,
-    jobProgress: {
-      jobId: input.jobId,
-      enabled: Boolean(input.isBackgroundJob)
-    }
+    policy: input.toolPolicy
   });
 
+  // Discover MCP external tools if enabled
+  let mcpCleanup: (() => Promise<void>) | null = null;
+  if (agent.mcp.enabled && agent.mcp.servers.length > 0) {
+    try {
+      // Build a minimal wrapExecute for MCP tools (policy + logging handled by createTools wrapExecute pattern)
+      const wrapMcp = <TInput, TOutput>(name: string, execute: (args: TInput) => Promise<TOutput>) => {
+        return async (args: TInput): Promise<TOutput> => {
+          const start = Date.now();
+          try {
+            const result = await execute(args);
+            toolCalls.push({ name, ok: true, duration_ms: Date.now() - start });
+            return result;
+          } catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            toolCalls.push({ name, ok: false, duration_ms: Date.now() - start, error });
+            throw err;
+          }
+        };
+      };
+      const mcp = await discoverMcpTools(agent, wrapMcp);
+      tools.push(...mcp.tools);
+      mcpCleanup = mcp.cleanup;
+      if (mcp.tools.length > 0) {
+        log(`MCP: discovered ${mcp.tools.length} external tools`);
+      }
+    } catch (err) {
+      log(`MCP discovery failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   if (process.env.DOTCLAW_SELF_CHECK === '1') {
     try {
       const details = await runSelfCheck({ model });
@@ -1250,6 +832,14 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     }
   }
 
+  // Resolve reasoning effort: input override > agent config > 'low'
+  const VALID_EFFORTS = ['off', 'low', 'medium', 'high'] as const;
+  const rawEffort = input.reasoningEffort || agent.reasoning?.effort || 'low';
+  const reasoningEffort = VALID_EFFORTS.includes(rawEffort as typeof VALID_EFFORTS[number]) ? rawEffort : 'low';
+  const resolvedReasoning = reasoningEffort === 'off'
+    ? undefined
+    : { effort: reasoningEffort as 'low' | 'medium' | 'high' };
+
   let prompt = input.prompt;
   if (input.isScheduledTask) {
     prompt = `[SCHEDULED TASK - You are running automatically, not in response to a user message. Use mcp__dotclaw__send_message if needed to communicate with the user.]\n\n${input.prompt}`;
@@ -1390,11 +980,11 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
   if (memoryPolicyResult) promptPackVersions['memory-policy'] = memoryPolicyResult.pack.version;
   if (memoryRecallResult) promptPackVersions['memory-recall'] = memoryRecallResult.pack.version;
 
-  const buildInstructions = (planBlockValue: string) => buildSystemInstructions({
+  const buildInstructions = () => buildSystemInstructions({
     assistantName,
     groupNotes: claudeNotes.group,
     globalNotes: claudeNotes.global,
-    skillNotes,
+    skillCatalog,
     memorySummary: sessionCtx.state.summary,
     memoryFacts: sessionCtx.state.facts,
     sessionRecall,
@@ -1405,73 +995,21 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     toolReliability: input.toolReliability,
     behaviorConfig: input.behaviorConfig,
     isScheduledTask: !!input.isScheduledTask,
-    isBackgroundTask: !!input.isBackgroundTask,
     taskId: input.taskId,
-    isBackgroundJob: !!input.isBackgroundJob,
-    jobId: input.jobId,
     timezone: typeof input.timezone === 'string' ? input.timezone : undefined,
     hostPlatform: typeof input.hostPlatform === 'string' ? input.hostPlatform : undefined,
-    planBlock: planBlockValue,
+    messagingPlatform: input.chatJid?.includes(':') ? input.chatJid.split(':')[0] : undefined,
     taskExtractionPack: taskPackResult?.pack || null,
     responseQualityPack: responseQualityResult?.pack || null,
     toolCallingPack: toolCallingResult?.pack || null,
     toolOutcomePack: toolOutcomeResult?.pack || null,
     memoryPolicyPack: memoryPolicyResult?.pack || null,
-    memoryRecallPack: memoryRecallResult?.pack || null
+    memoryRecallPack: memoryRecallResult?.pack || null,
+    maxToolSteps
   });
 
-  let planBlock = '';
-  let instructions = buildInstructions(planBlock);
-  let instructionsTokens = estimateTokensForModel(instructions, tokenEstimate.tokensPerChar);
-  let maxContextTokens = Math.max(config.maxContextTokens - config.maxOutputTokens - instructionsTokens, 2000);
-  let adjustedContextTokens = Math.max(1000, Math.floor(maxContextTokens * tokenRatio));
-  let { recentMessages: plannerContextMessages } = splitRecentHistory(recentMessages, adjustedContextTokens, 6);
-  plannerContextMessages = clampContextMessages(plannerContextMessages, tokenEstimate.tokensPerChar, maxContextMessageTokens);
-
-  if (shouldRunPlanner({
-    enabled: plannerEnabled,
-    mode: plannerMode,
-    prompt,
-    tokensPerChar: tokenEstimate.tokensPerChar,
-    minTokens: plannerMinTokens,
-    trigger: plannerTrigger
-  })) {
-    try {
-      const plannerStartedAt = Date.now();
-      const plannerPrompt = buildPlannerPrompt(plannerContextMessages);
-      const plannerResult = await openrouter.callModel({
-        model: plannerModel,
-        instructions: plannerPrompt.instructions,
-        input: plannerPrompt.input,
-        maxOutputTokens: plannerMaxOutputTokens,
-        temperature: plannerTemperature,
-        reasoning: { effort: 'low' as const }
-      });
-      const plannerText = await getTextWithFallback(plannerResult, 'planner');
-      const plan = parsePlannerResponse(plannerText);
-      if (plan) {
-        planBlock = formatPlanBlock(plan);
-      }
-      timings.planner_ms = Date.now() - plannerStartedAt;
-    } catch (err) {
-      log(`Planner failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  if (planBlock) {
-    instructions = buildInstructions(planBlock);
-    instructionsTokens = estimateTokensForModel(instructions, tokenEstimate.tokensPerChar);
-    maxContextTokens = Math.max(config.maxContextTokens - config.maxOutputTokens - instructionsTokens, 2000);
-    adjustedContextTokens = Math.max(1000, Math.floor(maxContextTokens * tokenRatio));
-    ({ recentMessages: plannerContextMessages } = splitRecentHistory(recentMessages, adjustedContextTokens, 6));
-    plannerContextMessages = clampContextMessages(plannerContextMessages, tokenEstimate.tokensPerChar, maxContextMessageTokens);
-  }
-
-  const buildContext = (extraInstruction?: string) => {
-    let resolvedInstructions = buildInstructions(planBlock);
-    if (extraInstruction) {
-      resolvedInstructions = `${resolvedInstructions}\n\n${extraInstruction}`;
-    }
+  const buildContext = () => {
+    const resolvedInstructions = buildInstructions();
     const resolvedInstructionTokens = estimateTokensForModel(resolvedInstructions, tokenEstimate.tokensPerChar);
     const resolvedMaxContext = Math.max(config.maxContextTokens - config.maxOutputTokens - resolvedInstructionTokens, 2000);
     const resolvedAdjusted = Math.max(1000, Math.floor(resolvedMaxContext * tokenRatio));
@@ -1487,17 +1025,13 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
   let responseText = '';
   let completionTokens = 0;
   let promptTokens = 0;
-  let modelToolCalls: Array<{ name: string }> = [];
-
   let latencyMs: number | undefined;
-  const runCompletion = async (extraInstruction?: string): Promise<{
-    responseText: string;
-    completionTokens: number;
-    promptTokens: number;
-    latencyMs?: number;
-    modelToolCalls: Array<{ name: string }>;
-  }> => {
-    const { instructions: resolvedInstructions, instructionsTokens: resolvedInstructionTokens, contextMessages } = buildContext(extraInstruction);
+
+  const modelChain = [model, ...(input.modelFallbacks || [])].slice(0, 3);
+  let currentModel = model;
+
+  try {
+    const { instructions: resolvedInstructions, instructionsTokens: resolvedInstructionTokens, contextMessages } = buildContext();
     const resolvedPromptTokens = resolvedInstructionTokens
       + estimateMessagesTokens(contextMessages, tokenEstimate.tokensPerChar, tokenEstimate.tokensPerMessage)
       + tokenEstimate.tokensPerRequest;
@@ -1512,127 +1046,107 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
       }
     }
 
-    log('Starting OpenRouter call...');
-    const startedAt = Date.now();
-    const callParams = {
-      model,
-      instructions: resolvedInstructions,
-      input: messagesToOpenRouter(contextMessages),
-      tools,
-      stopWhen: stepCountIs(maxToolSteps),
-      maxOutputTokens: config.maxOutputTokens,
-      temperature: config.temperature,
-      reasoning: { effort: 'low' as const }
-    };
-    const result = await openrouter.callModel(callParams);
-    const localLatencyMs = Date.now() - startedAt;
-
-    // Get the complete response text via the SDK's proper getText() path
-    let localResponseText = await getTextWithFallback(result, 'completion');
-
-    const toolCallsFromModel = await result.getToolCalls();
-    if (toolCallsFromModel.length > 0) {
-      log(`Model made ${toolCallsFromModel.length} tool call(s): ${toolCallsFromModel.map(t => t.name).join(', ')}`);
+    const contextInput = messagesToOpenRouter(contextMessages);
+
+    // Inject vision content into the last user message if images are present
+    const imageContent = loadImageAttachments(input.attachments);
+    if (imageContent.length > 0 && contextInput.length > 0) {
+      const lastMsg = contextInput[contextInput.length - 1];
+      if (lastMsg.role === 'user') {
+        // Convert string content to multi-modal content array
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (lastMsg as any).content = [
+          { type: 'text', text: typeof lastMsg.content === 'string' ? lastMsg.content : '' },
+          ...imageContent
+        ];
+      }
     }
 
-    if (!localResponseText || !localResponseText.trim()) {
-      if (toolCallsFromModel.length > 0) {
-        localResponseText = 'I started running tool calls but did not get a final response. If you want me to continue, please ask a narrower subtask or say "continue".';
-      } else {
-        // Responses API likely returned a gen-ID; retry with Chat Completions API
-        try {
-          localResponseText = await chatCompletionsFallback({
-            model,
-            instructions: resolvedInstructions,
-            messages: messagesToOpenRouter(contextMessages),
-            maxOutputTokens: config.maxOutputTokens,
-            temperature: config.temperature
-          });
-        } catch (err) {
-          log(`Chat Completions fallback error: ${err instanceof Error ? err.message : String(err)}`);
+    let lastError: unknown = null;
+    for (let attempt = 0; attempt < modelChain.length; attempt++) {
+      currentModel = modelChain[attempt];
+      if (attempt > 0) log(`Fallback ${attempt}: trying ${currentModel}`);
+
+      try {
+        log(`Starting OpenRouter call (${currentModel})...`);
+        const startedAt = Date.now();
+        const result = openrouter.callModel({
+          model: currentModel,
+          instructions: resolvedInstructions,
+          input: contextInput,
+          tools,
+          stopWhen: stepCountIs(maxToolSteps),
+          maxOutputTokens: config.maxOutputTokens,
+          temperature: config.temperature,
+          reasoning: resolvedReasoning
+        });
+
+        // Stream text chunks to IPC if streamDir is provided
+        if (input.streamDir) {
+          let seq = 0;
+          try {
+            fs.mkdirSync(input.streamDir, { recursive: true });
+            for await (const delta of result.getTextStream()) {
+              seq++;
+              const chunkFile = path.join(input.streamDir, `chunk_${String(seq).padStart(6, '0')}.txt`);
+              const tmpFile = chunkFile + '.tmp';
+              fs.writeFileSync(tmpFile, delta);
+              fs.renameSync(tmpFile, chunkFile);
+            }
+            fs.writeFileSync(path.join(input.streamDir, 'done'), '');
+          } catch (streamErr) {
+            log(`Stream error: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`);
+            try { fs.writeFileSync(path.join(input.streamDir, 'error'), streamErr instanceof Error ? streamErr.message : String(streamErr)); } catch { /* ignore */ }
+          }
         }
-      }
-      if (!localResponseText || !localResponseText.trim()) {
-        log(`Warning: Model returned empty/whitespace response after all fallbacks. tool calls: ${toolCallsFromModel.length}`);
-      }
-    } else {
-      log(`Model returned text response (${localResponseText.length} chars)`);
-    }
 
-    const localCompletionTokens = estimateTokensForModel(localResponseText || '', tokenEstimate.tokensPerChar);
-    return {
-      responseText: localResponseText,
-      completionTokens: localCompletionTokens,
-      promptTokens: resolvedPromptTokens,
-      latencyMs: localLatencyMs,
-      modelToolCalls: toolCallsFromModel
-    };
-  };
+        latencyMs = Date.now() - startedAt;
 
-  try {
-    const firstAttempt = await runCompletion();
-    responseText = firstAttempt.responseText;
-    completionTokens = firstAttempt.completionTokens;
-    promptTokens = firstAttempt.promptTokens;
-    latencyMs = firstAttempt.latencyMs;
-    modelToolCalls = firstAttempt.modelToolCalls;
-
-    const shouldValidate = responseValidateEnabled
-      && promptTokens >= responseValidateMinPromptTokens
-      && completionTokens >= responseValidateMinResponseTokens
-      && (responseValidateAllowToolCalls || modelToolCalls.length === 0);
-    if (shouldValidate) {
-      const MAX_VALIDATION_ITERATIONS = 5;
-      let retriesLeft = responseValidateMaxRetries;
-      for (let _validationIter = 0; _validationIter < MAX_VALIDATION_ITERATIONS; _validationIter++) {
-        if (!responseValidateAllowToolCalls && modelToolCalls.length > 0) {
-          break;
+        const completionResult = await getResponseText(result, 'completion');
+        responseText = completionResult.text;
+
+        const toolCallsFromModel = await result.getToolCalls();
+        if (toolCallsFromModel.length > 0) {
+          log(`Model made ${toolCallsFromModel.length} tool call(s): ${toolCallsFromModel.map(t => t.name).join(', ')}`);
         }
-        let validationResult: ResponseValidation | null = null;
         if (!responseText || !responseText.trim()) {
-          validationResult = { verdict: 'fail', issues: ['Response was empty.'], missing: [] };
-        } else {
-          try {
-            const validationStartedAt = Date.now();
-            validationResult = await validateResponseQuality({
-              openrouter,
-              model: responseValidateModel,
-              userPrompt: query,
-              response: responseText,
-              maxOutputTokens: responseValidateMaxOutputTokens,
-              temperature: responseValidateTemperature
-            });
-            timings.response_validation_ms = (timings.response_validation_ms ?? 0) + (Date.now() - validationStartedAt);
-          } catch (err) {
-            log(`Response validation failed: ${err instanceof Error ? err.message : String(err)}`);
+          if (completionResult.error) {
+            log(`Tool execution failed: ${completionResult.error}`);
+            responseText = `Something went wrong while processing your request: ${completionResult.error}. Please try again.`;
+          } else if (toolCallsFromModel.length > 0) {
+            responseText = 'I started running tool calls but did not get a final response. If you want me to continue, please ask a narrower subtask or say "continue".';
+          } else {
+            log(`Warning: Model returned empty/whitespace response. tool calls: ${toolCallsFromModel.length}`);
           }
+        } else {
+          log(`Model returned text response (${responseText.length} chars)`);
         }
-        if (!validationResult || validationResult.verdict === 'pass') {
-          break;
-        }
-        if (retriesLeft <= 0) {
-          break;
+
+        completionTokens = estimateTokensForModel(responseText || '', tokenEstimate.tokensPerChar);
+        promptTokens = resolvedPromptTokens;
+        lastError = null;
+        break; // Success
+      } catch (err) {
+        lastError = err;
+        if (classifyError(err) && attempt < modelChain.length - 1) {
+          log(`${currentModel} failed (${classifyError(err)}): ${err instanceof Error ? err.message : err}`);
+          continue;
         }
-        retriesLeft -= 1;
-        log(`Response validation failed; retrying (${retriesLeft} retries left)`);
-        const retryGuidance = buildRetryGuidance(validationResult);
-        const retryAttempt = await runCompletion(retryGuidance);
-        responseText = retryAttempt.responseText;
-        completionTokens = retryAttempt.completionTokens;
-        promptTokens = retryAttempt.promptTokens;
-        latencyMs = retryAttempt.latencyMs;
-        modelToolCalls = retryAttempt.modelToolCalls;
+        throw err; // Non-retryable or last model — propagate
       }
     }
+
+    if (lastError) throw lastError;
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
-    log(`Agent error: ${errorMessage}`);
+    const allFailed = modelChain.length > 1 ? `All models failed. Last error: ${errorMessage}` : errorMessage;
+    log(`Agent error: ${allFailed}`);
     return {
       status: 'error',
       result: null,
       newSessionId: isNew ? sessionCtx.sessionId : undefined,
-      error: errorMessage,
-      model,
+      error: allFailed,
+      model: currentModel,
       prompt_pack_versions: Object.keys(promptPackVersions).length > 0 ? promptPackVersions : undefined,
       memory_summary: sessionCtx.state.summary,
       memory_facts: sessionCtx.state.facts,
@@ -1649,25 +1163,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
   }
 
   appendHistory(sessionCtx, 'assistant', responseText || '');
-
   history = loadHistory(sessionCtx);
-  const newMessages = history.filter(m => m.seq > sessionCtx.state.lastSummarySeq);
-  if (newMessages.length >= config.summaryUpdateEveryMessages) {
-    const summaryUpdate = await updateMemorySummary({
-      openrouter,
-      model: summaryModel,
-      existingSummary: sessionCtx.state.summary,
-      existingFacts: sessionCtx.state.facts,
-      newMessages,
-      maxOutputTokens: config.summaryMaxOutputTokens
-    });
-    if (summaryUpdate) {
-      sessionCtx.state.summary = summaryUpdate.summary;
-      sessionCtx.state.facts = summaryUpdate.facts;
-      sessionCtx.state.lastSummarySeq = newMessages[newMessages.length - 1].seq;
-      saveMemoryState(sessionCtx);
-    }
-  }
 
   const runMemoryExtraction = async () => {
     const extractionMessages = history.slice(-memoryExtractionMaxMessages);
@@ -1680,7 +1176,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
       messages: extractionMessages,
       memoryPolicyPack: memoryPolicyResult?.pack || null
     });
-    const extractionResult = await openrouter.callModel({
+    const extractionResult = openrouter.callModel({
       model: memoryModel,
       instructions: extractionPrompt.instructions,
       input: extractionPrompt.input,
@@ -1688,7 +1184,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
       temperature: 0.1,
       reasoning: { effort: 'low' as const }
     });
-    const extractionText = await getTextWithFallback(extractionResult, 'memory_extraction');
+    const { text: extractionText } = await getResponseText(extractionResult, 'memory_extraction');
     const extractedItems = parseMemoryExtraction(extractionText);
     if (extractedItems.length === 0) return;
 
@@ -1722,27 +1218,11 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     timings.memory_extraction_ms = (timings.memory_extraction_ms ?? 0) + (Date.now() - extractionStartedAt);
   };
 
-  if (memoryExtractionEnabled && (!input.isScheduledTask || memoryExtractScheduled)) {
-    const runMemoryExtractionWithRetry = async (maxRetries = 2): Promise<void> => {
-      for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-          await runMemoryExtraction();
-          return;
-        } catch (err) {
-          log(`Memory extraction attempt ${attempt + 1} failed: ${err instanceof Error ? err.message : String(err)}`);
-          if (attempt < maxRetries) {
-            await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
-          }
-        }
-      }
-      log('Memory extraction failed after all retries');
-    };
-
-    if (memoryExtractionAsync && isDaemon) {
-      void runMemoryExtractionWithRetry().catch(() => {});
-    } else {
-      await runMemoryExtractionWithRetry();
-    }
+  if (memoryExtractionEnabled && isDaemon && (!input.isScheduledTask || memoryExtractScheduled)) {
+    // Fire-and-forget in daemon mode; skip entirely in ephemeral mode
+    void runMemoryExtraction().catch((err) => {
+      log(`Memory extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
   }
 
   // Normalize empty/whitespace-only responses to null
@@ -1754,11 +1234,16 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
     }
   }
 
+  // Cleanup MCP connections
+  if (mcpCleanup) {
+    try { await mcpCleanup(); } catch { /* ignore cleanup errors */ }
+  }
+
   return {
     status: 'success',
     result: finalResult,
     newSessionId: isNew ? sessionCtx.sessionId : undefined,
-    model,
+    model: currentModel,
     prompt_pack_versions: Object.keys(promptPackVersions).length > 0 ? promptPackVersions : undefined,
     memory_summary: sessionCtx.state.summary,
     memory_facts: sessionCtx.state.facts,