@dotsetlabs/dotclaw 2.5.0 → 2.6.1

package/.env.example

@@ -8,16 +8,18 @@
 # (they are NOT read from .env unless the script explicitly loads dotenv).
 
 # --- Required (app runtime) ---
+# Set at least one provider token (Telegram or Discord).
+
 # Telegram bot token from @BotFather
-TELEGRAM_BOT_TOKEN=123456789:replace-with-real-token
+# TELEGRAM_BOT_TOKEN=123456789:replace-with-real-token
+
+# Discord bot token (from Discord Developer Portal)
+# DISCORD_BOT_TOKEN=replace-with-discord-token
 
 # OpenRouter API key
 OPENROUTER_API_KEY=sk-or-replace-with-real-key
 
 # --- Optional (app runtime) ---
-# Discord bot token (enables Discord provider)
-# DISCORD_BOT_TOKEN=replace-with-discord-token
-
 # Brave Search API key (enables WebSearch tool in the agent)
 BRAVE_SEARCH_API_KEY=replace-with-brave-key
 
@@ -27,11 +29,8 @@ TZ=America/New_York
 # GitHub Personal Access Token (enables gh CLI in containers)
 # GH_TOKEN=ghp_your_token_here
 
-# OpenAI API key (enables OpenAI TTS provider; falls back to OPENROUTER_API_KEY)
-# OPENAI_API_KEY=sk-replace-with-openai-key
-
-# Override vision model for the AnalyzeImage tool (defaults to openai/gpt-4o)
-# DOTCLAW_VISION_MODEL=openai/gpt-4o
+# Container-only overrides (for example OPENAI_API_KEY or DOTCLAW_VISION_MODEL)
+# should be set per group in ~/.dotclaw/data/registered_groups.json under containerConfig.env.
 
 # --- Optional: System (set in shell before starting) ---
 # Override DotClaw home directory (defaults to ~/.dotclaw)
@@ -63,7 +62,7 @@ TZ=America/New_York
 # AUTOTUNE_OUTPUT_DIR=~/.dotclaw/prompts
 # AUTOTUNE_CANARY_FRACTION=0.1
 # AUTOTUNE_BEHAVIOR_CONFIG_PATH=~/.dotclaw/config/behavior.json
-# AUTOTUNE_BEHAVIOR_REPORT_DIR=~/.dotclaw/config
+# AUTOTUNE_BEHAVIOR_REPORT_DIR=~/.dotclaw/data
 # AUTOTUNE_BEHAVIOR_ENABLED=1
 
 # --- Internal (do not set) ---

package/README.md

@@ -23,9 +23,10 @@ Personal OpenRouter-based assistant for Telegram and Discord. Each request runs
 
 - Node.js 20+
 - Docker (running)
-- Telegram bot token (from @BotFather)
+- At least one provider token:
+  - Telegram bot token (from @BotFather), or
+  - Discord bot token
 - OpenRouter API key
-- Discord bot token (optional — for Discord provider)
 
 ## Quick Start
 
@@ -64,7 +65,10 @@ dotclaw groups       # List registered chats
 dotclaw build        # Build the Docker container image
 dotclaw add-instance # Create and start an isolated instance
 dotclaw instances    # List discovered instances
+dotclaw install-service   # Install launchd/systemd service
+dotclaw uninstall-service # Remove launchd/systemd service
 dotclaw version      # Show installed version
+dotclaw help         # Show help
 ```
 
 Instance flags:
@@ -80,7 +84,7 @@ All configuration and data is stored in `~/.dotclaw/`:
 
 ```
 ~/.dotclaw/
-  .env                    # Secrets (Telegram, OpenRouter keys)
+  .env                    # Secrets (provider tokens, OpenRouter key, optional Brave/GH keys)
   config/
     runtime.json          # Runtime overrides
     model.json            # Model selection
@@ -119,7 +123,7 @@ Or see:
 ## Development
 
 ```bash
-npm run dev          # Run with hot reload
+npm run dev          # Run from source (tsx)
 npm run dev:up       # Full dev cycle: rebuild container + kill stale daemons + start dev
 npm run dev:down     # Remove all running dotclaw agent containers
 npm run build        # Compile TypeScript (host)

package/config-examples/runtime.json

@@ -100,13 +100,13 @@
       },
       "bash": {
         "timeoutMs": 600000
-      },
-      "process": {
-        "maxSessions": 16,
-        "maxOutputBytes": 1048576,
-        "defaultTimeoutMs": 1800000
       }
     },
+    "process": {
+      "maxSessions": 16,
+      "maxOutputBytes": 1048576,
+      "defaultTimeoutMs": 1800000
+    },
     "tts": {
       "provider": "edge-tts",
       "openaiModel": "tts-1",

package/config-examples/tool-policy.json

@@ -13,6 +13,8 @@
       "Bash",
       "Python",
       "Browser",
+      "Process",
+      "AnalyzeImage",
       "mcp__dotclaw__send_message",
       "mcp__dotclaw__send_file",
       "mcp__dotclaw__send_photo",
@@ -41,14 +43,22 @@
       "mcp__dotclaw__memory_forget",
       "mcp__dotclaw__memory_list",
       "mcp__dotclaw__memory_search",
-      "mcp__dotclaw__memory_stats"
+      "mcp__dotclaw__memory_stats",
+      "mcp__dotclaw__get_config",
+      "mcp__dotclaw__set_tool_policy",
+      "mcp__dotclaw__set_behavior",
+      "mcp__dotclaw__set_mcp_config",
+      "mcp__dotclaw__subagent"
     ],
     "deny": [],
     "max_per_run": {
       "Bash": 128,
       "Python": 64,
       "WebSearch": 40,
-      "WebFetch": 60
+      "WebFetch": 60,
+      "Process": 128,
+      "AnalyzeImage": 16,
+      "mcp__dotclaw__subagent": 8
     },
     "default_max_per_run": 256
   }

package/container/agent-runner/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "dotclaw-agent-runner",
-  "version": "1.9.0",
+  "version": "2.3.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "dotclaw-agent-runner",
-      "version": "1.9.0",
+      "version": "2.3.1",
       "dependencies": {
         "@openrouter/sdk": "^0.3.0",
         "cron-parser": "^5.0.0",

package/container/agent-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotclaw-agent-runner",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "type": "module",
   "description": "Container-side agent runner for DotClaw",
   "main": "dist/index.js",

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

@@ -40,6 +40,7 @@ import {
   buildToolOutcomeFallback,
   compactToolConversationItems,
   detectToolExecutionRequirement,
+  buildMalformedArgumentsRecoveryHint,
   isNonRetryableToolError,
   normalizeToolCallArguments,
   normalizeToolCallSignature,
@@ -48,6 +49,15 @@ import {
   parseListReadNewestInstruction,
   shouldRetryIdempotentToolCall,
 } from './tool-loop-policy.js';
+import {
+  injectImagesIntoContextInput,
+  loadImageAttachmentsForInput,
+  messagesToOpenRouterInput,
+} from './openrouter-input.js';
+import {
+  extractFunctionCallsForReplay,
+  toReplayFunctionCallItems,
+} from './openrouter-followup.js';
 
 type OpenRouterResult = ReturnType<OpenRouter['callModel']>;
 
@@ -202,21 +212,6 @@ function extractTextFromApiResponse(response: any): string {
   return '';
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function extractFunctionCalls(response: any): Array<{ id: string; name: string; arguments: any }> {
-  const calls: Array<{ id: string; name: string; arguments: unknown }> = [];
-  for (const item of response?.output || []) {
-    if (item?.type === 'function_call') {
-      let args = item.arguments;
-      if (typeof args === 'string') {
-        try { args = JSON.parse(args); } catch { /* keep as string */ }
-      }
-      calls.push({ id: item.callId, name: item.name, arguments: args });
-    }
-  }
-  return calls;
-}
-
 function writeOutput(output: ContainerOutput): void {
   console.log(OUTPUT_START_MARKER);
   console.log(JSON.stringify(output));
@@ -513,55 +508,6 @@ function loadClaudeNotes(): { group: string | null; global: string | null } {
   };
 }
 
-
-// ── 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,
-    content: message.content
-  }));
-}
-
 function clampContextMessages(messages: Message[], tokensPerChar: number, maxTokens: number): Message[] {
   if (!Number.isFinite(maxTokens) || maxTokens <= 0) return messages;
   const tpc = tokensPerChar > 0 ? tokensPerChar : 0.25;
@@ -1287,21 +1233,12 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
       }
     }
 
-    const contextInput = messagesToOpenRouter(contextMessages);
+    const contextInput = messagesToOpenRouterInput(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
-        ];
-      }
-    }
+    // Inject vision content into the last user message if images are present.
+    // Uses OpenRouter Responses API content part types (input_text/input_image).
+    const imageContent = loadImageAttachmentsForInput(input.attachments, { log });
+    injectImagesIntoContextInput(contextInput, imageContent);
 
     let lastError: unknown = null;
     for (let attempt = 0; attempt < modelChain.length; attempt++) {
@@ -1363,7 +1300,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
         }
 
         responseText = extractTextFromApiResponse(lastResponse);
-        let pendingCalls = extractFunctionCalls(lastResponse);
+        let pendingCalls = extractFunctionCallsForReplay(lastResponse);
         const callSignatureCounts = new Map<string, number>();
         let previousRoundSignature = '';
         let repeatedRoundCount = 0;
@@ -1482,8 +1419,10 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
             reason: nudgeReason,
             attempt: toolRequirementNudgeAttempt
           });
-          const responseItems = Array.isArray(lastResponse?.output) ? lastResponse.output : [];
-          conversationInput = [...conversationInput, ...responseItems, { role: 'user', content: nudgePrompt }];
+          if (responseText) {
+            conversationInput = [...conversationInput, { role: 'assistant', content: responseText }];
+          }
+          conversationInput = [...conversationInput, { role: 'user', content: nudgePrompt }];
           try {
             const nudgeResult = openrouter.callModel({
               model: currentModel,
@@ -1500,7 +1439,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
               responseText = nudgeText;
               writeStreamChunk(nudgeText);
             }
-            pendingCalls = extractFunctionCalls(lastResponse);
+            pendingCalls = extractFunctionCallsForReplay(lastResponse);
           } catch (nudgeErr) {
             log(`Tool requirement nudge failed: ${nudgeErr instanceof Error ? nudgeErr.message : String(nudgeErr)}`);
             break;
@@ -1563,7 +1502,13 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
               rawArguments: fc.arguments
             });
             if (normalizedArgs.malformedReason) {
-              const error = `Malformed arguments for ${fc.name}: ${normalizedArgs.malformedReason}`;
+              const recoveryHint = buildMalformedArgumentsRecoveryHint({
+                toolName: fc.name,
+                malformedReason: normalizedArgs.malformedReason
+              });
+              const error = recoveryHint
+                ? `Malformed arguments for ${fc.name}: ${normalizedArgs.malformedReason}. ${recoveryHint}`
+                : `Malformed arguments for ${fc.name}: ${normalizedArgs.malformedReason}`;
               toolResults.push({
                 type: 'function_call_output',
                 callId: fc.id,
@@ -1634,7 +1579,8 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
 
           // Build follow-up input with FULL conversation context:
           // original messages + model output + tool results (accumulated each round)
-          conversationInput = [...conversationInput, ...lastResponse.output, ...toolResults];
+          const replayFunctionCalls = toReplayFunctionCallItems(pendingCalls);
+          conversationInput = [...conversationInput, ...replayFunctionCalls, ...toolResults];
 
           // Compact oversized tool payloads before follow-up calls to reduce context bloat.
           const compactedConversation = compactToolConversationItems(conversationInput, {
@@ -1741,7 +1687,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
                     responseText = retryText;
                     writeStreamChunk(retryText);
                   }
-                  pendingCalls = extractFunctionCalls(lastResponse);
+                  pendingCalls = extractFunctionCallsForReplay(lastResponse);
                   continue;
                 } catch (retryErr) {
                   log(`Context overflow retry failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
@@ -1761,7 +1707,7 @@ export async function runAgentOnce(input: ContainerInput): Promise<ContainerOutp
             writeStreamChunk(followupText);
           }
 
-          pendingCalls = extractFunctionCalls(lastResponse);
+          pendingCalls = extractFunctionCallsForReplay(lastResponse);
         }
 
         if (toolExecutionRequirement.required && toolCalls.length === 0) {

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

@@ -158,21 +158,121 @@ export function appendHistory(ctx: SessionContext, role: 'user' | 'assistant', c
   return message;
 }
 
+function safeStringifyHistoryValue(value: unknown): string {
+  try {
+    const serialized = JSON.stringify(value);
+    return typeof serialized === 'string' ? serialized : String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function coerceHistoryContentToString(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value == null) return '';
+
+  if (Array.isArray(value)) {
+    const parts = value
+      .map((part) => {
+        if (!part || typeof part !== 'object') return null;
+        const record = part as Record<string, unknown>;
+        if (typeof record.text === 'string' && record.text.trim()) return record.text;
+        if (typeof record.content === 'string' && record.content.trim()) return record.content;
+        if (typeof record.output === 'string' && record.output.trim()) return record.output;
+        if (typeof record.refusal === 'string' && record.refusal.trim()) return record.refusal;
+        return null;
+      })
+      .filter((part): part is string => typeof part === 'string');
+    if (parts.length > 0) return parts.join('\n');
+    return safeStringifyHistoryValue(value);
+  }
+
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    if (typeof record.text === 'string' && record.text.trim()) return record.text;
+    if (typeof record.content === 'string' && record.content.trim()) return record.content;
+    if (typeof record.output === 'string' && record.output.trim()) return record.output;
+    if (typeof record.refusal === 'string' && record.refusal.trim()) return record.refusal;
+    return safeStringifyHistoryValue(value);
+  }
+
+  return String(value);
+}
+
 export function loadHistory(ctx: SessionContext): Message[] {
   if (!fs.existsSync(ctx.historyPath)) return [];
-  const lines = fs.readFileSync(ctx.historyPath, 'utf-8').trim().split('\n');
+  const raw = fs.readFileSync(ctx.historyPath, 'utf-8');
+  if (!raw.trim()) return [];
+  const lines = raw.trim().split('\n');
   const messages: Message[] = [];
+  let needsRewrite = false;
+  let highestSeq = 0;
   for (const line of lines) {
-    if (!line.trim()) continue;
+    if (!line.trim()) {
+      needsRewrite = true;
+      continue;
+    }
     try {
-      const parsed = JSON.parse(line);
-      if (parsed?.role && parsed?.content) {
-        messages.push(parsed);
+      const parsed = JSON.parse(line) as Record<string, unknown>;
+      const role = parsed?.role === 'user' || parsed?.role === 'assistant'
+        ? parsed.role
+        : null;
+      if (!role) {
+        needsRewrite = true;
+        continue;
+      }
+
+      const content = coerceHistoryContentToString(parsed.content);
+      if (typeof parsed.content !== 'string') {
+        needsRewrite = true;
+      }
+
+      const timestamp = typeof parsed.timestamp === 'string' && parsed.timestamp
+        ? parsed.timestamp
+        : new Date().toISOString();
+      if (timestamp !== parsed.timestamp) {
+        needsRewrite = true;
       }
+
+      const parsedSeq = Number(parsed.seq);
+      const seq = Number.isFinite(parsedSeq) && parsedSeq > 0
+        ? Math.floor(parsedSeq)
+        : (highestSeq + 1);
+      if (seq !== parsedSeq) {
+        needsRewrite = true;
+      }
+      highestSeq = Math.max(highestSeq, seq);
+
+      messages.push({
+        role,
+        content,
+        timestamp,
+        seq
+      });
     } catch {
-      // ignore malformed lines
+      needsRewrite = true;
     }
   }
+
+  messages.sort((a, b) => a.seq - b.seq);
+  let nextSeq = 1;
+  for (const message of messages) {
+    if (message.seq < nextSeq) {
+      message.seq = nextSeq;
+      needsRewrite = true;
+    }
+    nextSeq = message.seq + 1;
+  }
+
+  if (ctx.meta.nextSeq < nextSeq) {
+    ctx.meta.nextSeq = nextSeq;
+    saveSessionMeta(ctx);
+  }
+
+  if (needsRewrite) {
+    writeHistory(ctx, messages);
+  }
+
   return messages;
 }
 

package/container/agent-runner/src/openrouter-followup.ts

@@ -0,0 +1,87 @@
+type RawRecord = Record<string, unknown>;
+
+export type ExtractedFunctionCall = {
+  id: string;
+  itemId?: string;
+  name: string;
+  arguments: unknown;
+  argumentsText: string;
+};
+
+export type ReplayFunctionCallItem = {
+  type: 'function_call';
+  id: string;
+  callId: string;
+  name: string;
+  arguments: string;
+};
+
+function normalizeCallId(record: RawRecord): { callId?: string; itemId?: string } {
+  const callId = typeof record.callId === 'string' && record.callId.trim()
+    ? record.callId.trim()
+    : (typeof record.id === 'string' && record.id.trim() ? record.id.trim() : undefined);
+  const itemId = typeof record.id === 'string' && record.id.trim()
+    ? record.id.trim()
+    : undefined;
+  return { callId, itemId };
+}
+
+function normalizeArguments(raw: unknown): { arguments: unknown; argumentsText: string } {
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    if (!trimmed) return { arguments: {}, argumentsText: '{}' };
+    try {
+      return { arguments: JSON.parse(trimmed), argumentsText: trimmed };
+    } catch {
+      return { arguments: raw, argumentsText: raw };
+    }
+  }
+  if (raw == null) return { arguments: {}, argumentsText: '{}' };
+  try {
+    const serialized = JSON.stringify(raw);
+    if (typeof serialized === 'string') {
+      return { arguments: raw, argumentsText: serialized };
+    }
+  } catch {
+    // fall through
+  }
+  return { arguments: raw, argumentsText: String(raw) };
+}
+
+function extractFromOutput(output: unknown[]): ExtractedFunctionCall[] {
+  const calls: ExtractedFunctionCall[] = [];
+  for (const item of output) {
+    if (!item || typeof item !== 'object') continue;
+    const record = item as RawRecord;
+    if (record.type !== 'function_call') continue;
+    const { callId, itemId } = normalizeCallId(record);
+    const name = typeof record.name === 'string' ? record.name.trim() : '';
+    if (!callId || !name) continue;
+    const normalizedArguments = normalizeArguments(record.arguments);
+    calls.push({
+      id: callId,
+      itemId,
+      name,
+      arguments: normalizedArguments.arguments,
+      argumentsText: normalizedArguments.argumentsText
+    });
+  }
+  return calls;
+}
+
+export function extractFunctionCallsForReplay(response: unknown): ExtractedFunctionCall[] {
+  if (!response || typeof response !== 'object') return [];
+  const output = (response as { output?: unknown }).output;
+  if (!Array.isArray(output)) return [];
+  return extractFromOutput(output);
+}
+
+export function toReplayFunctionCallItems(calls: ExtractedFunctionCall[]): ReplayFunctionCallItem[] {
+  return calls.map((call) => ({
+    type: 'function_call',
+    id: call.itemId || call.id,
+    callId: call.id,
+    name: call.name,
+    arguments: call.argumentsText || '{}'
+  }));
+}