@swarmclawai/swarmclaw 0.4.0 → 0.5.0

package/src/lib/server/process-manager.ts

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { spawn, type ChildProcessWithoutNullStreams } from 'child_process'
 
 const MAX_LOG_CHARS = 200_000
@@ -99,7 +99,7 @@ function getShellCommand(command: string): { shell: string; args: string[] } {
 }
 
 export async function startManagedProcess(opts: StartProcessOptions): Promise<StartProcessResult> {
-  const id = crypto.randomBytes(8).toString('hex')
+  const id = genId(8)
   const timeoutMs = Math.max(1000, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
   const yieldMs = Math.max(250, opts.yieldMs ?? DEFAULT_BACKGROUND_YIELD_MS)
   const startedAt = now()

package/src/lib/server/queue.ts

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadTasks, saveTasks, loadQueue, saveQueue, loadAgents, loadSchedules, saveSchedules, loadSessions, saveSessions, loadSettings } from './storage'
 import { notify } from './ws-hub'
 import { WORKSPACE_DIR } from './data-dir'
@@ -9,6 +9,7 @@ import { pushMainLoopEventToMainSessions } from './main-agent-loop'
 import { executeSessionChatTurn } from './chat-execution'
 import { extractTaskResult, formatResultBody } from './task-result'
 import { getCheckpointSaver } from './langgraph-checkpoint'
+import { isProtectedMainSession } from './main-session'
 import type { Agent, BoardTask, Message } from '@/types'
 
 let processing = false
@@ -82,7 +83,7 @@ function pushQueueUnique(queue: string[], id: string): void {
 }
 
 function isMainSession(session: SessionLike | null | undefined): boolean {
-  return session?.name === '__main__'
+  return isProtectedMainSession(session)
 }
 
 function resolveTaskOwnerUser(task: ScheduleTaskMeta, sessions: Record<string, SessionLike>): string | null {
@@ -155,7 +156,11 @@ function notifyMainChatScheduleResult(task: BoardTask): void {
   const fallbackText = runSession ? latestAssistantText(runSession) : ''
 
   // Zod-validated structured extraction: one pass to get summary + all artifacts
-  const taskResult = extractTaskResult(runSession, task.result || fallbackText || null)
+  const taskResult = extractTaskResult(
+    runSession,
+    task.result || fallbackText || null,
+    { sinceTime: typeof task.startedAt === 'number' ? task.startedAt : null },
+  )
   const resultBody = formatResultBody(taskResult)
 
   const statusLabel = task.status === 'completed' ? 'completed' : 'failed'
@@ -224,7 +229,11 @@ function notifyAgentThreadTaskResult(task: BoardTask): void {
   const runSessionId = typeof task.sessionId === 'string' ? task.sessionId : ''
   const runSession = runSessionId ? sessions[runSessionId] : null
   const fallbackText = runSession ? latestAssistantText(runSession) : ''
-  const taskResult = extractTaskResult(runSession, task.result || fallbackText || null)
+  const taskResult = extractTaskResult(
+    runSession,
+    task.result || fallbackText || null,
+    { sinceTime: typeof task.startedAt === 'number' ? task.startedAt : null },
+  )
   const resultBody = formatResultBody(taskResult)
 
   const statusLabel = task.status === 'completed' ? 'completed' : 'failed'
@@ -374,7 +383,7 @@ export function validateCompletedTasksQueue() {
     task.updatedAt = now
     if (!task.comments) task.comments = []
     task.comments.push({
-      id: crypto.randomBytes(4).toString('hex'),
+      id: genId(),
       author: 'System',
       text: `Task auto-failed completed-queue validation.\n\n${validation.reasons.map((r) => `- ${r}`).join('\n')}`,
       createdAt: now,
@@ -413,7 +422,7 @@ function scheduleRetryOrDeadLetter(task: BoardTask, reason: string): 'retry' | '
     task.error = `Retry scheduled after failure: ${reason}`.slice(0, 500)
     if (!task.comments) task.comments = []
     task.comments.push({
-      id: crypto.randomBytes(4).toString('hex'),
+      id: genId(),
       author: 'System',
       text: `Attempt ${task.attempts}/${task.maxAttempts} failed. Retrying in ${delaySec}s.\n\nReason: ${reason}`,
       createdAt: now,
@@ -428,7 +437,7 @@ function scheduleRetryOrDeadLetter(task: BoardTask, reason: string): 'retry' | '
   task.error = `Dead-lettered after ${task.attempts}/${task.maxAttempts} attempts: ${reason}`.slice(0, 500)
   if (!task.comments) task.comments = []
   task.comments.push({
-    id: crypto.randomBytes(4).toString('hex'),
+    id: genId(),
     author: 'System',
     text: `Task moved to dead-letter after ${task.attempts}/${task.maxAttempts} attempts.\n\nReason: ${reason}`,
     createdAt: now,
@@ -610,7 +619,11 @@ export async function processNext() {
           applyTaskPolicyDefaults(t2[taskId])
           // Structured extraction: Zod-validated result with typed artifacts
           const runSessions = loadSessions()
-          const taskResult = extractTaskResult(runSessions[sessionId], result || null)
+          const taskResult = extractTaskResult(
+            runSessions[sessionId],
+            result || null,
+            { sinceTime: typeof t2[taskId].startedAt === 'number' ? t2[taskId].startedAt : null },
+          )
           const enrichedResult = formatResultBody(taskResult)
           t2[taskId].result = enrichedResult.slice(0, 4000) || null
           t2[taskId].updatedAt = Date.now()
@@ -636,7 +649,7 @@ export async function processNext() {
               updatedAt: now,
             }
             t2[taskId].comments!.push({
-              id: crypto.randomBytes(4).toString('hex'),
+              id: genId(),
               author: agent.name,
               agentId: agent.id,
               text: `Task completed.\n\n${result?.slice(0, 1000) || 'No summary provided.'}`,
@@ -647,7 +660,7 @@ export async function processNext() {
             const retryState = scheduleRetryOrDeadLetter(t2[taskId], failureReason)
             t2[taskId].completedAt = retryState === 'dead_lettered' ? null : t2[taskId].completedAt
             t2[taskId].comments!.push({
-              id: crypto.randomBytes(4).toString('hex'),
+              id: genId(),
               author: agent.name,
               agentId: agent.id,
               text: `Task failed validation and was not marked completed.\n\n${validation.reasons.map((r) => `- ${r}`).join('\n')}`,
@@ -739,7 +752,7 @@ export async function processNext() {
           const isRepeatError = lastComment?.agentId === agent.id && lastComment?.text.startsWith('Task failed')
           if (!isRepeatError) {
             t2[taskId].comments!.push({
-              id: crypto.randomBytes(4).toString('hex'),
+              id: genId(),
               author: agent.name,
               agentId: agent.id,
               text: 'Task failed — see error details above.',

package/src/lib/server/scheduler.ts

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadSchedules, saveSchedules, loadAgents, loadTasks, saveTasks } from './storage'
 import { enqueueTask } from './queue'
 import { CronExpressionParser } from 'cron-parser'
@@ -157,7 +157,7 @@ async function tick() {
       prev.runNumber = schedule.runNumber
     } else {
       // Create a new linked task (first run or previous task still in-flight)
-      taskId = crypto.randomBytes(4).toString('hex')
+      taskId = genId()
       tasks[taskId] = {
         id: taskId,
         title: `[Sched] ${schedule.name} (run #${schedule.runNumber})`,

package/src/lib/server/session-mailbox.ts

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadSessions, saveSessions } from './storage'
 
 export type MailboxStatus = 'new' | 'ack'
@@ -58,7 +58,7 @@ export function sendMailboxEnvelope(input: {
     ? Math.max(0, Math.min(7 * 24 * 3600, Math.trunc(input.ttlSec)))
     : null
   const envelope: MailboxEnvelope = {
-    id: crypto.randomBytes(6).toString('hex'),
+    id: genId(6),
     type: (input.type || 'message').trim() || 'message',
     payload: String(input.payload || ''),
     fromSessionId: input.fromSessionId || null,

package/src/lib/server/session-run-manager.ts

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import type { SSEEvent } from '@/types'
 import { active, loadSessions } from './storage'
 import { executeSessionChatTurn, type ExecuteChatTurnResult } from './chat-execution'
@@ -420,7 +420,7 @@ export function enqueueSessionRun(input: EnqueueSessionRunInput): EnqueueSession
     }
   }
 
-  const runId = crypto.randomBytes(8).toString('hex')
+  const runId = genId(8)
   const run: SessionRunRecord = {
     id: runId,
     sessionId: input.sessionId,

package/src/lib/server/session-tools/connector.ts

@@ -58,6 +58,10 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
                 const outbound = connector.config?.outboundJid?.trim()
                 if (outbound) channelId = outbound
               }
+              if (!channelId) {
+                const outbound = connector.config?.outboundTarget?.trim()
+                if (outbound) channelId = outbound
+              }
               if (!channelId) {
                 const recentChannelId = getConnectorRecentChannelId(selected.id)
                 if (recentChannelId) channelId = recentChannelId
@@ -67,7 +71,11 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
                 if (allowed.length) channelId = allowed[0]
               }
               if (!channelId) {
-                return `Error: no target recipient configured. Provide "to", or set connector config "outboundJid"/"allowedJids".`
+                const allowed = connector.config?.allowFrom?.split(',').map((s: string) => s.trim()).filter(Boolean) || []
+                if (allowed.length) channelId = allowed[0]
+              }
+              if (!channelId) {
+                return `Error: no target recipient configured. Provide "to", or set connector config "outboundJid"/"allowedJids"/"outboundTarget"/"allowFrom".`
               }
               if (connector.platform === 'whatsapp') {
                 channelId = normalizeWhatsAppTarget(channelId)
@@ -93,18 +101,57 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
               })
             }
 
+            if (action === 'message_react' || action === 'message_edit' || action === 'message_pin' || action === 'message_delete') {
+              if (!connectorId) return 'Error: connectorId is required for rich messaging actions.'
+              const { getRunningInstance } = await import('../connectors/manager')
+              const inst = getRunningInstance(connectorId)
+              if (!inst) return `Error: connector "${connectorId}" is not running.`
+
+              const targetChannel = to?.trim() || ''
+              const targetMessageId = message?.trim() || ''
+              if (!targetMessageId) return 'Error: message parameter (used as messageId) is required for rich messaging actions.'
+
+              try {
+                if (action === 'message_react') {
+                  if (!inst.sendReaction) return 'Error: this connector does not support reactions.'
+                  const emoji = caption?.trim() || '👍'
+                  await inst.sendReaction(targetChannel, targetMessageId, emoji)
+                  return JSON.stringify({ status: 'reacted', connectorId, messageId: targetMessageId, emoji })
+                }
+                if (action === 'message_edit') {
+                  if (!inst.editMessage) return 'Error: this connector does not support message editing.'
+                  const newText = caption?.trim() || ''
+                  if (!newText) return 'Error: caption (new text) is required for message_edit.'
+                  await inst.editMessage(targetChannel, targetMessageId, newText)
+                  return JSON.stringify({ status: 'edited', connectorId, messageId: targetMessageId })
+                }
+                if (action === 'message_delete') {
+                  if (!inst.deleteMessage) return 'Error: this connector does not support message deletion.'
+                  await inst.deleteMessage(targetChannel, targetMessageId)
+                  return JSON.stringify({ status: 'deleted', connectorId, messageId: targetMessageId })
+                }
+                if (action === 'message_pin') {
+                  if (!inst.pinMessage) return 'Error: this connector does not support message pinning.'
+                  await inst.pinMessage(targetChannel, targetMessageId)
+                  return JSON.stringify({ status: 'pinned', connectorId, messageId: targetMessageId })
+                }
+              } catch (err: unknown) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`
+              }
+            }
+
             return 'Unknown action. Use list_running, list_targets, or send.'
-          } catch (err: any) {
-            return `Error: ${err.message || String(err)}`
+          } catch (err: unknown) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
           name: 'connector_message_tool',
-          description: 'Send proactive outbound messages through running connectors (for example WhatsApp status updates). Supports listing running connectors/targets and sending text plus optional media (URLs or local file paths).',
+          description: 'Send proactive outbound messages and perform rich messaging actions through running connectors. Supports listing running connectors/targets, sending text/media, and rich messaging (react, edit, delete, pin). For rich actions: connectorId + message (as messageId) required; caption carries emoji for react or new text for edit.',
           schema: z.object({
-            action: z.enum(['list_running', 'list_targets', 'send']).describe('connector messaging action'),
+            action: z.enum(['list_running', 'list_targets', 'send', 'message_react', 'message_edit', 'message_delete', 'message_pin']).describe('connector messaging action'),
             connectorId: z.string().optional().describe('Optional connector id. Defaults to the first running connector (or first for selected platform).'),
-            platform: z.string().optional().describe('Optional platform filter (whatsapp, telegram, slack, discord).'),
+            platform: z.string().optional().describe('Optional platform filter (whatsapp, telegram, slack, discord, bluebubbles, etc.).'),
             to: z.string().optional().describe('Target channel id / recipient. For WhatsApp, phone number or full JID.'),
             message: z.string().optional().describe('Message text to send (required for send action).'),
             imageUrl: z.string().optional().describe('Optional public image URL to attach/send where platform supports media.'),

package/src/lib/server/session-tools/crud.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
 import fs from 'fs'
 import path from 'path'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { spawnSync } from 'child_process'
 import * as cheerio from 'cheerio'
 import {
@@ -342,7 +342,7 @@ export function buildCrudTools(bctx: ToolBuildContext): StructuredToolInterface[
                   })
                 }
               }
-              const newId = crypto.randomBytes(4).toString('hex')
+              const newId = genId()
               const entry = {
                 id: newId,
                 ...parsed,
@@ -565,7 +565,7 @@ export function buildCrudTools(bctx: ToolBuildContext): StructuredToolInterface[
               const content = trimDocumentContent(extracted.text)
               if (!content) return 'Error: extracted document text is empty.'
 
-              const docId = crypto.randomBytes(6).toString('hex')
+              const docId = genId(6)
               const now = Date.now()
               const parsedMetadata = metadata && typeof metadata === 'string'
                 ? (() => {

package/src/lib/server/session-tools/delegate.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { spawn, spawnSync } from 'child_process'
 import { loadAgents, loadTasks, upsertTask } from '../storage'
 import { log } from '../logger'
@@ -199,6 +199,21 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
                   return
                 }
 
+                // If resume failed because the session no longer exists, clear the stale ID
+                // and return a targeted error so the agent retries without resume
+                if (resumeIdToUse && /No conversation found/i.test(stdout + stderr)) {
+                  persistDelegateResumeId('claudeCode', null)
+                  log.warn('session-tools', 'delegate_to_claude_code stale resume ID cleared', {
+                    sessionId: ctx?.sessionId || null,
+                    staleResumeId: resumeIdToUse,
+                  })
+                  finish(
+                    `Error: The previous Claude Code session (${resumeIdToUse}) has expired and was cleared. ` +
+                    'Retry the task with resume=false to start a fresh session.',
+                  )
+                  return
+                }
+
                 const successText = assistantText.trim() || stdout.trim() || stderr.trim()
                 if (code === 0 && successText) {
                   const out = discoveredSessionId
@@ -230,7 +245,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_claude_code',
-          description: 'Delegate a complex task to Claude Code CLI. Use for tasks that need deep code understanding, multi-file refactoring, or running tests. The task runs in the session working directory.',
+          description: 'Delegate a complex multi-file coding task to Claude Code CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for Claude Code'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved Claude delegation session for this SwarmClaw session'),
@@ -442,7 +457,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_codex_cli',
-          description: 'Delegate a complex task to Codex CLI. Use for deep coding/refactor tasks and shell-driven implementation work.',
+          description: 'Delegate a complex multi-file coding task to Codex CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for Codex CLI'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved Codex delegation thread for this SwarmClaw session'),
@@ -607,7 +622,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_opencode_cli',
-          description: 'Delegate a complex task to OpenCode CLI. Use for deep coding/refactor tasks and shell-driven implementation work.',
+          description: 'Delegate a complex multi-file coding task to OpenCode CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for OpenCode CLI'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved OpenCode delegation session for this SwarmClaw session'),
@@ -640,7 +655,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
             }
             if (!target) return `Error: Agent "${targetAgentId}" not found. Use the agent directory in your system prompt to find valid agent IDs.`
 
-            const taskId = crypto.randomBytes(4).toString('hex')
+            const taskId = genId()
             const now = Date.now()
             const newTask = {
               id: taskId,
@@ -648,12 +663,13 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
               description: taskDesc || taskPrompt,
               status: 'todo',
               agentId: resolvedId,
+              cwd,
               sourceType: 'delegation' as const,
               delegatedByAgentId: ctx.agentId!,
               createdAt: now,
               updatedAt: now,
               comments: [{
-                id: crypto.randomBytes(4).toString('hex'),
+                id: genId(),
                 author: agents[ctx.agentId!]?.name || 'Agent',
                 agentId: ctx.agentId!,
                 text: `Delegated from ${agents[ctx.agentId!]?.name || ctx.agentId}`,

package/src/lib/server/session-tools/file.ts

@@ -26,8 +26,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             const resolved = safePath(bctx.cwd, filePath)
             const content = fs.readFileSync(resolved, 'utf-8')
             return truncate(content, MAX_FILE)
-          } catch (err: any) {
-            return `Error reading file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error reading file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -44,22 +44,28 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
   if (canWriteFiles) {
     tools.push(
       tool(
-        async ({ filePath, content }) => {
+        async ({ filePath, content, encoding }) => {
           try {
             const resolved = safePath(bctx.cwd, filePath)
             fs.mkdirSync(path.dirname(resolved), { recursive: true })
+            if (encoding === 'base64') {
+              const buf = Buffer.from(content, 'base64')
+              fs.writeFileSync(resolved, buf)
+              return `File written: ${filePath} (${buf.length} bytes, binary)`
+            }
             fs.writeFileSync(resolved, content, 'utf-8')
             return `File written: ${filePath} (${content.length} bytes)`
-          } catch (err: any) {
-            return `Error writing file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error writing file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
           name: 'write_file',
-          description: 'Write content to a file in the session working directory. Creates directories if needed.',
+          description: 'Write content to a file in the session working directory. Creates directories if needed. For PDFs and styled reports, use the create_document tool instead. For other binary files (Excel, images, zip, etc.), set encoding to "base64" and pass base64-encoded content.',
           schema: z.object({
             filePath: z.string().describe('Relative path to the file'),
-            content: z.string().describe('The content to write'),
+            content: z.string().describe('The content to write. For binary files, this must be a base64-encoded string.'),
+            encoding: z.enum(['utf-8', 'base64']).optional().describe('Encoding of the content. Use "base64" for binary files like PDF, Excel, images, zip archives. Defaults to "utf-8" for plain text.'),
           }),
         },
       ),
@@ -74,8 +80,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             const resolved = safePath(bctx.cwd, dirPath || '.')
             const tree = listDirRecursive(resolved, 0, 3)
             return tree.length ? tree.join('\n') : '(empty directory)'
-          } catch (err: any) {
-            return `Error listing files: ${err.message}`
+          } catch (err: unknown) {
+            return `Error listing files: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -103,8 +109,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             fs.mkdirSync(path.dirname(destination), { recursive: true })
             fs.copyFileSync(source, destination)
             return `File copied: ${sourcePath} -> ${destinationPath}`
-          } catch (err: any) {
-            return `Error copying file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error copying file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -135,8 +141,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             if (fs.existsSync(destination) && overwrite) fs.unlinkSync(destination)
             fs.renameSync(source, destination)
             return `File moved: ${sourcePath} -> ${destinationPath}`
-          } catch (err: any) {
-            return `Error moving file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error moving file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -169,8 +175,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             }
             fs.rmSync(resolved, { recursive: !!recursive, force: !!force })
             return `Deleted: ${filePath}`
-          } catch (err: any) {
-            return `Error deleting file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error deleting file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -214,8 +220,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             } else {
               return `[Download ${basename}](/api/uploads/${filename})`
             }
-          } catch (err: any) {
-            return `Error sending file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error sending file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -229,6 +235,173 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
     )
   }
 
+  if (canSendFiles || canWriteFiles) {
+    // create_document: markdown → pdf / html / png / jpg
+    tools.push(
+      tool(
+        async ({ content, title, filename, format }) => {
+          try {
+            const fmt = format || 'pdf'
+            const { marked } = await import('marked')
+            const html = await marked.parse(content)
+            const safeTitle = (title || 'Document').replace(/</g, '&lt;')
+            const fullHtml = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>${safeTitle}</title>
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;max-width:800px;margin:40px auto;padding:0 20px;color:#1a1a1a;line-height:1.6}
+h1{font-size:28px;border-bottom:2px solid #e5e7eb;padding-bottom:8px}
+h2{font-size:22px;margin-top:32px}
+h3{font-size:18px;margin-top:24px}
+pre{background:#f3f4f6;padding:16px;border-radius:8px;overflow-x:auto;font-size:13px}
+code{background:#f3f4f6;padding:2px 6px;border-radius:4px;font-size:13px}
+pre code{background:none;padding:0}
+table{border-collapse:collapse;width:100%}
+th,td{border:1px solid #d1d5db;padding:8px 12px;text-align:left}
+th{background:#f9fafb;font-weight:600}
+blockquote{border-left:4px solid #d1d5db;margin:16px 0;padding:8px 16px;color:#4b5563}
+img{max-width:100%}
+</style></head><body>${html}</body></html>`
+
+            const defaultBase = (title || 'document').replace(/[^a-zA-Z0-9_-]/g, '_')
+
+            if (fmt === 'html') {
+              const outName = filename || `${defaultBase}.html`
+              const resolved = safePath(bctx.cwd, outName)
+              fs.mkdirSync(path.dirname(resolved), { recursive: true })
+              fs.writeFileSync(resolved, fullHtml, 'utf-8')
+              return `HTML document created: ${outName} (${fullHtml.length} bytes)`
+            }
+
+            const { chromium } = await import('playwright')
+            const browser = await chromium.launch({ headless: true })
+            try {
+              const page = await browser.newPage()
+              await page.setContent(fullHtml, { waitUntil: 'networkidle' })
+
+              if (fmt === 'pdf') {
+                const outName = filename || `${defaultBase}.pdf`
+                const resolved = safePath(bctx.cwd, outName)
+                fs.mkdirSync(path.dirname(resolved), { recursive: true })
+                await page.pdf({ path: resolved, format: 'A4', margin: { top: '40px', bottom: '40px', left: '40px', right: '40px' }, printBackground: true })
+                return `PDF created: ${outName}`
+              }
+
+              // png or jpg screenshot
+              const ext = fmt === 'jpg' ? 'jpeg' : 'png'
+              const outName = filename || `${defaultBase}.${fmt}`
+              const resolved = safePath(bctx.cwd, outName)
+              fs.mkdirSync(path.dirname(resolved), { recursive: true })
+              await page.screenshot({ path: resolved, type: ext, fullPage: true })
+              const size = fs.statSync(resolved).size
+              return `Image created: ${outName} (${(size / 1024).toFixed(1)} KB)`
+            } finally {
+              await browser.close()
+            }
+          } catch (err: unknown) {
+            return `Error creating document: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+        {
+          name: 'create_document',
+          description: 'Create a document from markdown content. Renders markdown with professional styling and outputs as PDF, HTML, or image. Use this instead of write_file for PDFs, reports, styled pages, or document screenshots. After creating, use send_file to deliver it to the user.',
+          schema: z.object({
+            content: z.string().describe('Markdown content for the document'),
+            title: z.string().optional().describe('Document title (shown in header and used for default filename)'),
+            filename: z.string().optional().describe('Output filename (defaults to title-based name with appropriate extension)'),
+            format: z.enum(['pdf', 'html', 'png', 'jpg']).optional().describe('Output format. "pdf" (default) for print-ready documents, "html" for web pages, "png"/"jpg" for images.'),
+          }),
+        },
+      ),
+    )
+
+    // create_spreadsheet: JSON data → xlsx or csv
+    tools.push(
+      tool(
+        async ({ data, headers, sheetName, filename, format }) => {
+          try {
+            const fmt = format || 'xlsx'
+            let rows: Record<string, unknown>[]
+            try {
+              rows = JSON.parse(data)
+              if (!Array.isArray(rows)) return 'Error: data must be a JSON array of objects'
+            } catch {
+              return 'Error: data is not valid JSON. Pass a JSON array of objects, e.g. [{"name":"Alice","age":30}]'
+            }
+
+            if (!rows.length) return 'Error: data array is empty'
+
+            // Resolve column headers: explicit headers, or keys from first row
+            const cols = headers?.length
+              ? headers
+              : Object.keys(rows[0] && typeof rows[0] === 'object' ? rows[0] : {})
+            if (!cols.length) return 'Error: could not determine column headers. Pass headers or use objects with keys.'
+
+            const defaultBase = (sheetName || 'spreadsheet').replace(/[^a-zA-Z0-9_-]/g, '_')
+
+            if (fmt === 'csv') {
+              const escapeCsv = (val: unknown): string => {
+                const s = val == null ? '' : String(val)
+                return s.includes(',') || s.includes('"') || s.includes('\n')
+                  ? `"${s.replace(/"/g, '""')}"`
+                  : s
+              }
+              const lines = [cols.map(escapeCsv).join(',')]
+              for (const row of rows) {
+                const r = Array.isArray(row) ? row : cols.map((c) => (row as Record<string, unknown>)[c])
+                lines.push(r.map(escapeCsv).join(','))
+              }
+              const outName = filename || `${defaultBase}.csv`
+              const resolved = safePath(bctx.cwd, outName)
+              fs.mkdirSync(path.dirname(resolved), { recursive: true })
+              fs.writeFileSync(resolved, lines.join('\n'), 'utf-8')
+              return `CSV created: ${outName} (${rows.length} rows, ${cols.length} columns)`
+            }
+
+            // xlsx via exceljs
+            const ExcelJS = await import('exceljs')
+            const workbook = new ExcelJS.default.Workbook()
+            const sheet = workbook.addWorksheet(sheetName || 'Sheet1')
+
+            sheet.columns = cols.map((c) => ({ header: c, key: c, width: Math.max(12, c.length + 4) }))
+            // Style header row
+            sheet.getRow(1).font = { bold: true }
+            sheet.getRow(1).fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF3F4F6' } }
+
+            for (const row of rows) {
+              if (Array.isArray(row)) {
+                const obj: Record<string, unknown> = {}
+                cols.forEach((c, i) => { obj[c] = row[i] })
+                sheet.addRow(obj)
+              } else {
+                sheet.addRow(row)
+              }
+            }
+
+            const outName = filename || `${defaultBase}.xlsx`
+            const resolved = safePath(bctx.cwd, outName)
+            fs.mkdirSync(path.dirname(resolved), { recursive: true })
+            await workbook.xlsx.writeFile(resolved)
+            const size = fs.statSync(resolved).size
+            return `Excel spreadsheet created: ${outName} (${rows.length} rows, ${cols.length} columns, ${(size / 1024).toFixed(1)} KB)`
+          } catch (err: unknown) {
+            return `Error creating spreadsheet: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+        {
+          name: 'create_spreadsheet',
+          description: 'Create an Excel (.xlsx) or CSV file from structured data. Pass data as a JSON array of objects. Use this for tables, reports, data exports, and any tabular data the user requests. After creating, use send_file to deliver it to the user.',
+          schema: z.object({
+            data: z.string().describe('JSON array of objects, e.g. [{"name":"Alice","score":95},{"name":"Bob","score":87}]'),
+            headers: z.array(z.string()).optional().describe('Column headers in display order. If omitted, keys from the first object are used.'),
+            sheetName: z.string().optional().describe('Worksheet name (default "Sheet1")'),
+            filename: z.string().optional().describe('Output filename (defaults to sheetName-based name with extension)'),
+            format: z.enum(['xlsx', 'csv']).optional().describe('Output format: "xlsx" (default) for Excel, "csv" for plain CSV.'),
+          }),
+        },
+      ),
+    )
+  }
+
   if (bctx.hasTool('edit_file')) {
     tools.push(
       tool(
@@ -243,8 +416,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             const updated = content.replace(oldText, newText)
             fs.writeFileSync(resolved, updated, 'utf-8')
             return `Successfully edited ${filePath}`
-          } catch (err: any) {
-            return `Error editing file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error editing file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {