@swarmclawai/swarmclaw 0.7.7 → 0.8.0

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

@@ -206,6 +206,109 @@ describe('delegate fallback', () => {
     assert.match(String(output.response || ''), /codex fallback ok/i)
   })
 
+  it('uses nested data.task payloads from recent tool-call wrappers', () => {
+    const output = runWithFakeDelegates(`
+      const mod = await import('./src/lib/server/session-tools/delegate.ts')
+      const { buildDelegateTools } = mod.default || mod['module.exports'] || mod
+
+      const tools = buildDelegateTools({
+        cwd: process.cwd(),
+        ctx: { sessionId: 'session-test', agentId: 'agent-test', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'delegate',
+        hasTool: (name) => name === 'delegate',
+        cleanupFns: [],
+        commandTimeoutMs: 5000,
+        claudeTimeoutMs: 5000,
+        cliProcessTimeoutMs: 5000,
+        persistDelegateResumeId: () => {},
+        readStoredDelegateResumeId: () => null,
+        resolveCurrentSession: () => null,
+        activePlugins: ['delegate'],
+      })
+
+      const delegateTool = tools.find((tool) => tool.name === 'delegate')
+      const raw = await delegateTool.invoke({
+        input: JSON.stringify({
+          data: {
+            task: 'Create a simple to-do list application.',
+          },
+        }),
+      })
+      console.log(raw)
+    `)
+
+    assert.equal(output.backend, 'codex')
+    assert.equal(output.status, 'completed')
+    assert.match(String(output.response || ''), /codex fallback ok/i)
+  })
+
+  it('falls back to reason text when malformed delegate wrappers omit task', () => {
+    const output = runWithFakeDelegates(`
+      const mod = await import('./src/lib/server/session-tools/delegate.ts')
+      const { buildDelegateTools } = mod.default || mod['module.exports'] || mod
+
+      const tools = buildDelegateTools({
+        cwd: process.cwd(),
+        ctx: { sessionId: 'session-test', agentId: 'agent-test', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'delegate',
+        hasTool: (name) => name === 'delegate',
+        cleanupFns: [],
+        commandTimeoutMs: 5000,
+        claudeTimeoutMs: 5000,
+        cliProcessTimeoutMs: 5000,
+        persistDelegateResumeId: () => {},
+        readStoredDelegateResumeId: () => null,
+        resolveCurrentSession: () => null,
+        activePlugins: ['delegate'],
+      })
+
+      const delegateTool = tools.find((tool) => tool.name === 'delegate')
+      const raw = await delegateTool.invoke({
+        input: JSON.stringify({
+          parameters: {
+            tool_id: 'delegate',
+            reason: 'Building a simple front-end to-do list app is well-suited for a delegated agent.',
+            subagent_tool_id: 'agent_coder',
+            subagent_name: 'Coder',
+          },
+        }),
+      })
+      console.log(raw)
+    `)
+
+    assert.equal(output.backend, 'codex')
+    assert.equal(output.status, 'completed')
+    assert.match(String(output.response || ''), /codex fallback ok/i)
+  })
+
+  it('accepts legacy id fields for lifecycle delegate actions', () => {
+    const output = runWithFakeDelegates(`
+      const mod = await import('./src/lib/server/session-tools/delegate.ts')
+      const { buildDelegateTools } = mod.default || mod['module.exports'] || mod
+
+      const tools = buildDelegateTools({
+        cwd: process.cwd(),
+        ctx: { sessionId: 'session-test', agentId: 'agent-test', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'delegate',
+        hasTool: (name) => name === 'delegate',
+        cleanupFns: [],
+        commandTimeoutMs: 5000,
+        claudeTimeoutMs: 5000,
+        cliProcessTimeoutMs: 5000,
+        persistDelegateResumeId: () => {},
+        readStoredDelegateResumeId: () => null,
+        resolveCurrentSession: () => null,
+        activePlugins: ['delegate'],
+      })
+
+      const delegateTool = tools.find((tool) => tool.name === 'delegate')
+      const raw = await delegateTool.invoke({ action: 'status', id: 'job-123' })
+      console.log(JSON.stringify({ raw }))
+    `)
+
+    assert.match(String(output.raw || ''), /delegation job "job-123" not found/i)
+  })
+
   it('ranks authenticated delegate backends ahead of unauthenticated ones', () => {
     const output = runWithFakeDelegates(`
       const mod = await import('./src/lib/server/provider-health.ts')

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

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { resolveDelegateResumeConfig } from './delegate'
+
+describe('resolveDelegateResumeConfig', () => {
+  it('auto-resumes when a stored backend resume ID exists', () => {
+    const config = resolveDelegateResumeConfig(
+      { task: 'continue the implementation' },
+      'codex',
+      {
+        readStoredDelegateResumeId: (key) => key === 'codex' ? 'codex-thread-42' : null,
+      },
+    )
+
+    assert.deepEqual(config, {
+      resume: true,
+      resumeId: '',
+    })
+  })
+
+  it('respects explicit resume=false even when a stored ID exists', () => {
+    const config = resolveDelegateResumeConfig(
+      { task: 'start fresh', resume: false },
+      'claude',
+      {
+        readStoredDelegateResumeId: () => 'claude-session-99',
+      },
+    )
+
+    assert.deepEqual(config, {
+      resume: false,
+      resumeId: '',
+    })
+  })
+
+  it('treats an explicit resumeId as an instruction to resume immediately', () => {
+    const config = resolveDelegateResumeConfig(
+      { task: 'continue', resumeId: 'gemini-session-5' },
+      'gemini',
+      {
+        readStoredDelegateResumeId: () => null,
+      },
+    )
+
+    assert.deepEqual(config, {
+      resume: true,
+      resumeId: 'gemini-session-5',
+    })
+  })
+})

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

@@ -147,6 +147,41 @@ function coerceDelegateBackend(value: unknown): DelegateBackend | null {
   return null
 }
 
+function asDelegateRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function pickNonEmptyDelegateString(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      continue
+    }
+    return trimmed
+  }
+  return null
+}
+
+function pickDelegateTaskText(record: Record<string, unknown> | null): string | null {
+  if (!record) return null
+  return pickNonEmptyDelegateString(
+    record.task,
+    record.prompt,
+    record.request,
+    record.instructions,
+    record.instruction,
+    record.description,
+    record.input,
+    record.reason,
+    record.goal,
+    record.objective,
+  )
+}
+
 function buildDelegateTaskFromPayload(normalized: Record<string, unknown>): string | null {
   const action = String(normalized.action || '').trim().toLowerCase()
   const target = [
@@ -200,20 +235,41 @@ function buildDelegateTaskFromPayload(normalized: Record<string, unknown>): stri
 
 function normalizeDelegateArgs(rawArgs: Record<string, unknown>): Record<string, unknown> {
   const normalized = normalizeToolInputArgs(rawArgs)
+  const nestedData = asDelegateRecord(normalized.data)
+  const delegatePayload = {
+    ...(nestedData || {}),
+    ...normalized,
+  }
   const backend = coerceDelegateBackend(
-    normalized.backend
-    ?? normalized.tool_name
-    ?? normalized.toolName
-    ?? normalized.delegate
-    ?? normalized.provider,
+    delegatePayload.backend
+    ?? delegatePayload.tool_name
+    ?? delegatePayload.toolName
+    ?? delegatePayload.tool
+    ?? delegatePayload.delegate
+    ?? delegatePayload.provider
+    ?? delegatePayload.subagent_tool_id
+    ?? delegatePayload.subagent_name,
   )
   if (backend && !normalized.backend) normalized.backend = backend
-  if (typeof normalized.task !== 'string' && typeof normalized.prompt === 'string') normalized.task = normalized.prompt
-  const action = String(normalized.action || '').trim().toLowerCase()
+  if (typeof normalized.task !== 'string' || !normalized.task.trim()) {
+    const directTask = pickDelegateTaskText(delegatePayload) || pickDelegateTaskText(nestedData)
+    if (directTask) normalized.task = directTask
+  }
+  const lifecycleJobId = pickNonEmptyDelegateString(
+    normalized.jobId,
+    normalized.id,
+    nestedData?.jobId,
+    nestedData?.id,
+  )
+  if (lifecycleJobId && (!normalized.jobId || typeof normalized.jobId !== 'string')) {
+    normalized.jobId = lifecycleJobId
+  }
+  const action = String(normalized.action ?? nestedData?.action ?? '').trim().toLowerCase()
   const isLifecycleAction = ['status', 'list', 'wait', 'cancel'].includes(action)
+  if (action) normalized.action = action
   if (!isLifecycleAction) {
     if (typeof normalized.task !== 'string' || !normalized.task.trim()) {
-      const synthesized = buildDelegateTaskFromPayload(normalized)
+      const synthesized = buildDelegateTaskFromPayload(delegatePayload)
       if (synthesized) normalized.task = synthesized
     }
     normalized.action = 'start'
@@ -247,12 +303,48 @@ function bindDelegateRuntime(runtime: DelegateRuntimeState | undefined, child: C
   child.once('error', clear)
 }
 
+function coerceOptionalBool(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false
+  }
+  return null
+}
+
+function resumeStorageKeyForBackend(
+  backend: 'claude' | 'codex' | 'opencode' | 'gemini',
+): 'claudeCode' | 'codex' | 'opencode' | 'gemini' {
+  if (backend === 'claude') return 'claudeCode'
+  if (backend === 'codex') return 'codex'
+  if (backend === 'opencode') return 'opencode'
+  return 'gemini'
+}
+
+export function resolveDelegateResumeConfig(
+  normalized: Record<string, unknown>,
+  backend: 'claude' | 'codex' | 'opencode' | 'gemini',
+  bctx: { readStoredDelegateResumeId?: (key: 'claudeCode' | 'codex' | 'opencode' | 'gemini') => string | null },
+): { resume: boolean; resumeId: string } {
+  const explicitResumeId = typeof normalized.resumeId === 'string' ? normalized.resumeId.trim() : ''
+  if (explicitResumeId) return { resume: true, resumeId: explicitResumeId }
+
+  const explicitResume = coerceOptionalBool(normalized.resume)
+  if (explicitResume !== null) return { resume: explicitResume, resumeId: '' }
+
+  const storedResumeId = bctx.readStoredDelegateResumeId?.(resumeStorageKeyForBackend(backend))
+  return {
+    resume: Boolean(storedResumeId),
+    resumeId: '',
+  }
+}
+
 async function runDelegateBackend(args: Record<string, unknown>, bctx: DelegateContext, runtime?: DelegateRuntimeState): Promise<string> {
   const normalized = normalizeDelegateArgs(args)
   const task = normalized.task as string
   const backend = ((normalized.backend as string) || 'claude') as DelegateBackend
-  const resume = normalized.resume as boolean
-  const resumeId = normalized.resumeId as string
+  const { resume, resumeId } = resolveDelegateResumeConfig(normalized, backend, bctx)
   const backends = {
     claude: findBinaryOnPath('claude'),
     codex: findBinaryOnPath('codex'),

package/src/lib/server/session-tools/discovery-approvals.test.ts

@@ -167,4 +167,146 @@ describe('discovery approval flows', () => {
     assert.equal(output.toolNames.includes('manage_schedules'), true)
     assert.equal(output.toolNames.includes('manage_platform'), false)
   })
+
+  it('session-granted builtins disabled by default still appear in the next turn tool list', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const toolsMod = await import('./src/lib/server/session-tools/index.ts')
+      const storage = storageMod.default || storageMod
+      const toolsApi = toolsMod.default || toolsMod
+
+      const now = Date.now()
+      storage.saveSessions({
+        session_email: {
+          id: 'session_email',
+          name: 'Email Tool Test',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'tester',
+          provider: 'openai',
+          model: 'gpt-test',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: now,
+          lastActiveAt: now,
+          sessionType: 'human',
+          agentId: 'default',
+          plugins: ['email'],
+        },
+      })
+
+      const built = await toolsApi.buildSessionTools(process.env.WORKSPACE_DIR, ['email'], {
+        sessionId: 'session_email',
+        agentId: 'default',
+        platformAssignScope: 'self',
+      })
+      console.log(JSON.stringify({
+        toolNames: built.tools.map((entry) => entry.name).sort(),
+      }))
+    `)
+
+    assert.equal(output.toolNames.includes('email'), true)
+  })
+
+  it('discover reports session-granted builtin tools as available now', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const toolsMod = await import('./src/lib/server/session-tools/index.ts')
+      const storage = storageMod.default || storageMod
+      const toolsApi = toolsMod.default || toolsMod
+
+      const now = Date.now()
+      storage.saveSessions({
+        session_discover_email: {
+          id: 'session_discover_email',
+          name: 'Discovery Email Test',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'tester',
+          provider: 'openai',
+          model: 'gpt-test',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: now,
+          lastActiveAt: now,
+          sessionType: 'human',
+          agentId: 'default',
+          plugins: ['email'],
+        },
+      })
+
+      const built = await toolsApi.buildSessionTools(process.env.WORKSPACE_DIR, ['email'], {
+        sessionId: 'session_discover_email',
+        agentId: 'default',
+        platformAssignScope: 'self',
+      })
+      const tool = built.tools.find((entry) => entry.name === 'manage_capabilities')
+      const raw = await tool.invoke({ action: 'discover', reason: 'Check runtime tool availability.' })
+      const plugins = JSON.parse(raw)
+      const email = plugins.find((entry) => entry.id === 'email')
+      console.log(JSON.stringify({
+        email,
+      }))
+    `)
+
+    assert.equal(output.email.granted, true)
+    assert.equal(output.email.availableNow, true)
+  })
+
+  it('hydrates agent-approved tools into stale connector sessions on the next turn', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const toolsMod = await import('./src/lib/server/session-tools/index.ts')
+      const approvalsMod = await import('./src/lib/server/approvals.ts')
+      const storage = storageMod.default || storageMod
+      const toolsApi = toolsMod.default || toolsMod
+      const approvals = approvalsMod.default || approvalsMod
+
+      const now = Date.now()
+      storage.saveSettings({ approvalsEnabled: true })
+      storage.saveSessions({
+        connector_session: {
+          id: 'connector_session',
+          name: 'Connector Session',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'connector',
+          provider: 'openai',
+          model: 'gpt-test',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: now,
+          lastActiveAt: now,
+          sessionType: 'human',
+          agentId: 'agent_1',
+          plugins: ['browser'],
+        },
+      })
+
+      const approval = approvals.requestApproval({
+        category: 'tool_access',
+        title: 'Enable connector tool',
+        description: 'Grant connector messaging',
+        data: { toolId: 'connector_message_tool', pluginId: 'connector_message_tool' },
+        agentId: 'agent_1',
+        sessionId: null,
+      })
+      await approvals.submitDecision(approval.id, true)
+
+      const built = await toolsApi.buildSessionTools(process.env.WORKSPACE_DIR, ['browser'], {
+        sessionId: 'connector_session',
+        agentId: 'agent_1',
+        platformAssignScope: 'self',
+      })
+      try {
+        const session = storage.loadSessions().connector_session
+        console.log(JSON.stringify({
+          toolNames: built.tools.map((entry) => entry.name).sort(),
+          plugins: session.plugins || [],
+        }))
+      } finally {
+        await built.cleanup()
+      }
+    `)
+
+    assert.equal(output.toolNames.includes('connector_message_tool'), true)
+    assert.equal(output.plugins.includes('connector_message_tool'), true)
+  })
 })

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

@@ -1,12 +1,32 @@
 import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
 import type { ToolBuildContext } from './context'
-import { getPluginManager } from '../plugins'
+import { getPluginManager, normalizeMarketplacePluginUrl } from '../plugins'
 import type { Plugin, PluginHooks, ClawHubSkill } from '@/types'
 import { searchClawHub } from '../clawhub-client'
 import { normalizeToolInputArgs } from './normalize-tool-args'
 import { pluginIdMatches } from '../tool-aliases'
 import { loadSessions } from '../storage'
+import { inferPluginPublisherSourceFromUrl } from '@/lib/plugin-sources'
+
+function trimString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function buildDiscoveryApprovalResumeInput(approval: import('@/types').ApprovalRequest): Record<string, unknown> | null {
+  if (approval.category !== 'plugin_install') return null
+  const url = trimString(approval.data.url)
+  if (!url) return null
+  const pluginId = trimString(approval.data.pluginId)
+  const reason = trimString(approval.data.reason)
+  return {
+    action: 'install_request',
+    url,
+    pluginId: pluginId || undefined,
+    reason: reason || `Approved install request for ${url}`,
+    approved: true,
+  }
+}
 
 /**
  * Unified Discovery Logic
@@ -41,11 +61,15 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
       case 'list':
       case 'discover': {
         const plugins = manager.listPlugins()
+        const currentSession = bctx?.ctx?.sessionId ? loadSessions()[bctx.ctx.sessionId] : null
+        const sessionPlugins = currentSession?.plugins || currentSession?.tools || []
         return JSON.stringify(plugins.map(p => ({
           id: p.filename,
           name: p.name,
           description: p.description,
           enabled: p.enabled,
+          granted: pluginIdMatches(sessionPlugins, p.filename),
+          availableNow: pluginIdMatches(sessionPlugins, p.filename) && !manager.isExplicitlyDisabled(p.filename),
           isBuiltin: !p.filename.endsWith('.js') && !p.filename.endsWith('.mjs')
         })), null, 2)
       }
@@ -62,6 +86,7 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
               description: s.description,
               author: s.author,
               source: 'clawhub',
+              catalogSource: 'clawhub',
               url: (s as ClawHubSkill & { rawUrl?: string }).rawUrl ?? s.url
             })))
           }
@@ -71,14 +96,32 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
 
         try {
           console.log('[discovery] Searching SwarmClaw registry...')
-          const scRes = await fetch('https://swarmclaw.ai/registry/plugins.json', { signal: AbortSignal.timeout(5000) })
-          if (scRes.ok) {
+          const registryResults = new Map<string, Record<string, unknown>>()
+          const registries = [
+            { url: 'https://swarmclaw.ai/registry/plugins.json', catalogSource: 'swarmclaw-site' },
+            { url: 'https://raw.githubusercontent.com/swarmclawai/swarmforge/main/registry.json', catalogSource: 'swarmforge' },
+          ] as const
+          for (const registry of registries) {
+            const scRes = await fetch(registry.url, { signal: AbortSignal.timeout(5000) })
+            if (!scRes.ok) continue
             const scPlugins = await scRes.json()
             const filtered = (scPlugins as Record<string, unknown>[]).filter((p: Record<string, unknown>) =>
               !q || (String(p.name || '')).toLowerCase().includes(q.toLowerCase()) || (String(p.description || '')).toLowerCase().includes(q.toLowerCase())
             )
-            results.push(...filtered.map(p => ({ ...p, source: 'swarmclaw' })))
+            for (const p of filtered) {
+              const id = String(p.id || p.name || '').trim().toLowerCase().replace(/[^a-z0-9]/g, '_')
+              if (!id || registryResults.has(id)) continue
+              const url = normalizeMarketplacePluginUrl(String(p.url || ''))
+              registryResults.set(id, {
+                ...p,
+                id,
+                url,
+                source: inferPluginPublisherSourceFromUrl(url) || 'swarmforge',
+                catalogSource: registry.catalogSource,
+              })
+            }
           }
+          results.push(...registryResults.values())
         } catch (err: unknown) {
           console.error('[discovery] SC Registry search failed:', err instanceof Error ? err.message : String(err))
         }
@@ -99,12 +142,12 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
           const currentSession = allSessions[bctx.ctx.sessionId]
           const grantedTools = currentSession?.plugins || currentSession?.tools || []
           if (currentSession && pluginIdMatches(grantedTools, pluginId)) {
-            return JSON.stringify({
-              alreadyGranted: true,
-              pluginId,
-              message: `You already have access to "${pluginId}" — proceed to use it directly.`,
-            })
-          }
+          return JSON.stringify({
+            alreadyGranted: true,
+            pluginId,
+            message: `You already have access to "${pluginId}". If it was just granted, it will be available on the next agent turn.`,
+          })
+        }
         }
         const { requestApprovalMaybeAutoApprove } = await import('../approvals')
         const approval = await requestApprovalMaybeAutoApprove({
@@ -121,7 +164,7 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
             pluginId,
             toolId: pluginId,
             autoApproved: true,
-            message: `Access to "${pluginId}" was auto-approved and granted. Proceed to use it directly.`,
+            message: `Access to "${pluginId}" was auto-approved and granted. It will be available on the next agent turn.`,
           })
         }
         return JSON.stringify({
@@ -182,7 +225,32 @@ async function executeDiscoveryAction(args: Record<string, unknown>, bctx?: Tool
 const DiscoveryPlugin: Plugin = {
   name: 'Core Discovery',
   description: 'Discover available plugins, search marketplaces, request access, or suggest new installs.',
-  hooks: {} as PluginHooks,
+  hooks: {
+    getApprovalGuidance: ({ approval, phase, approved }) => {
+      if (approval.category !== 'plugin_install') return null
+      if (phase === 'request') {
+        return [
+          'When this approval is granted, continue with `manage_capabilities` for the exact approved install request instead of asking again in prose.',
+          'Do not change the approved plugin URL or pluginId unless newer tool evidence proves the approved source is invalid.',
+        ]
+      }
+      if (phase === 'connector_reminder') {
+        return 'Approving this lets the agent resume the approved plugin install request without repeating marketplace research.'
+      }
+      if (approved !== true) {
+        return 'Do not retry the rejected install request unless the plugin source or requested capability materially changes.'
+      }
+      const resumeInput = buildDiscoveryApprovalResumeInput(approval)
+      const lines = [
+        'Resume immediately with `manage_capabilities` for the approved install request.',
+        'Do not repeat the same marketplace search or install request once approval has been granted.',
+      ]
+      if (resumeInput) {
+        lines.push(`Exact tool input: ${JSON.stringify(resumeInput)}`)
+      }
+      return lines
+    },
+  } as PluginHooks,
   tools: [
     {
       name: 'manage_capabilities',

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

@@ -83,6 +83,24 @@ describe('normalizeFileArgs', () => {
     assert.deepEqual(out.files, [{ name: 'report.md', content: '# report' }])
   })
 
+  it('parses stringified bulk file arrays from wrapped payloads', () => {
+    const out = normalizeFileArgs({
+      input: JSON.stringify({
+        action: 'write',
+        files: JSON.stringify([
+          { path: 'offer-pack/offer-brief.md', content: '# brief' },
+          { path: 'offer-pack/landing-copy.md', content: '# landing' },
+        ]),
+      }),
+    })
+
+    assert.equal(out.action, 'write')
+    assert.deepEqual(out.files, [
+      { path: 'offer-pack/offer-brief.md', content: '# brief' },
+      { path: 'offer-pack/landing-copy.md', content: '# landing' },
+    ])
+  })
+
   it('treats trailing-slash write targets as directory creation', async () => {
     const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'file-write-dir-'))
     const out = await executeFileAction({
@@ -95,4 +113,22 @@ describe('normalizeFileArgs', () => {
     assert.equal(fs.statSync(path.join(cwd, 'weather_update')).isDirectory(), true)
     fs.rmSync(cwd, { recursive: true, force: true })
   })
+
+  it('does not inline binary screenshot data when reading image files', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'file-read-binary-'))
+    const imagePath = path.join(cwd, 'screenshot-main.png')
+    fs.writeFileSync(imagePath, Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0x01, 0x02, 0x03]))
+
+    try {
+      const out = await executeFileAction({
+        action: 'read',
+        filePath: 'screenshot-main.png',
+      }, { cwd })
+
+      assert.match(out, /Binary file: screenshot-main\.png/)
+      assert.match(out, /Use send_file/)
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
 })