@swarmclawai/swarmclaw 0.6.7 → 0.7.0

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

@@ -1,255 +1,170 @@
 import { z } from 'zod'
-import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { tool } from '@langchain/core/tools'
 import fs from 'fs'
 import { genId } from '@/lib/id'
-import { getMemoryDb, getMemoryLookupLimits, storeMemoryImageAsset } from '../memory-db'
+import {
+  filterMemoriesByScope,
+  getMemoryDb,
+  getMemoryLookupLimits,
+  normalizeMemoryScopeMode,
+  storeMemoryImageAsset,
+} from '../memory-db'
 import { loadSettings } from '../storage'
+import { expandQuery } from '../query-expansion'
+import type { MemoryEntry, Plugin, PluginHooks } from '@/types'
 import type { ToolBuildContext } from './context'
+import { getPluginManager } from '../plugins'
+import { normalizeToolInputArgs } from './normalize-tool-args'
 
-export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterface[] {
-  const tools: StructuredToolInterface[] = []
-  const { ctx, hasTool } = bctx
+/**
+ * Advanced Database-Backed Memory logic.
+ */
+async function executeMemoryAction(input: any, ctx: any) {
+  const normalized = normalizeToolInputArgs((input ?? {}) as Record<string, unknown>)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const n = normalized as Record<string, any>
+  const {
+    action, key, value, query, scope, rerank,
+    scopeSessionId, projectRoot, filePaths, references, project,
+    linkedMemoryIds, depth, linkedLimit, targetIds,
+    tags, pinned, sharedWith
+  } = n
+  const category = typeof n.category === 'string' ? n.category : 'note'
+  const imagePath = typeof n.imagePath === 'string' ? n.imagePath : undefined
+  
+  const memDb = getMemoryDb()
+  const currentAgentId = ctx?.agentId || null
+  const rawScope = typeof scope === 'string' ? scope : 'auto'
+  const scopeMode = normalizeMemoryScopeMode(rawScope === 'shared' ? 'global' : rawScope)
+  const rerankMode = rerank === 'semantic' || rerank === 'lexical' ? rerank : 'balanced'
+  
+  const scopeFilter = {
+    mode: scopeMode,
+    agentId: currentAgentId,
+    sessionId: (typeof scopeSessionId === 'string' && scopeSessionId.trim()) ? scopeSessionId.trim() : (ctx?.sessionId || null),
+    projectRoot: (typeof projectRoot === 'string' && projectRoot.trim()) ? projectRoot.trim() : ((project && typeof project === 'object' && 'rootPath' in project && typeof (project as Record<string, unknown>).rootPath === 'string') ? (project as Record<string, unknown>).rootPath as string : null),
+  }
+  
+  const filterScope = (rows: MemoryEntry[]) => filterMemoriesByScope(rows, scopeFilter)
+  const canReadMemory = (m: MemoryEntry) => filterScope([m]).length > 0
+  const canMutateMemory = (m: MemoryEntry) => !m?.agentId || m.agentId === currentAgentId
 
-  if (hasTool('memory')) {
-    const memDb = getMemoryDb()
+  const limits = getMemoryLookupLimits(loadSettings())
+  const maxPerLookup = limits.maxPerLookup
 
-    tools.push(
-      tool(
-        async (input) => {
-          const { action, key, value, category, query, scope, filePaths, references, project, imagePath, linkedMemoryIds, depth, linkedLimit, targetIds, tags, pinned, sharedWith } = input as Record<string, any>
-          try {
-            const scopeMode = scope || 'auto'
-            const currentAgentId = ctx?.agentId || null
-            const canAccessMemory = (m: any) => !m?.agentId || m.agentId === currentAgentId
-            const filterScope = (rows: any[]) => {
-              if (scopeMode === 'shared') return rows.filter((m) => !m.agentId)
-              if (scopeMode === 'agent') return rows.filter((m) => currentAgentId && m.agentId === currentAgentId)
-              return rows.filter(canAccessMemory)
-            }
+  const formatEntry = (m: any) => {
+    let line = `[${m.id}] (${m.agentId ? `agent:${m.agentId}` : 'shared'}) ${m.category}/${m.title}: ${m.content}`
+    if (m.reinforcementCount) line += ` (reinforced ×${m.reinforcementCount})`
+    if (m.references?.length) {
+      line += `\n  refs: ${m.references.map((r: any) => `${r.type}:${r.path || r.title || r.type}`).join(', ')}`
+    }
+    if (m.imagePath) line += `\n  image: ${m.imagePath}`
+    if (m.linkedMemoryIds?.length) line += `\n  linked: ${m.linkedMemoryIds.join(', ')}`
+    return line
+  }
 
-            const limits = getMemoryLookupLimits(loadSettings())
-            const requestedDepth = typeof depth === 'number' ? depth : 0
-            const requestedLinkedLimit = typeof linkedLimit === 'number' ? linkedLimit : limits.maxLinkedExpansion
-            const effectiveDepth = Math.max(0, Math.min(requestedDepth, limits.maxDepth))
-            const effectiveLinkedLimit = Math.max(0, Math.min(requestedLinkedLimit, limits.maxLinkedExpansion))
-            const maxPerLookup = limits.maxPerLookup
+  if (action === 'store') {
+    let storedImage: any = null
+    if (imagePath && fs.existsSync(imagePath)) {
+      storedImage = await storeMemoryImageAsset(imagePath, genId(6))
+    }
+    const entry = memDb.add({
+      agentId: scopeMode === 'global' ? null : currentAgentId,
+      sessionId: ctx?.sessionId || null,
+      category: category || 'note',
+      title: key,
+      content: value || '',
+      references: Array.isArray(references) ? references : [],
+      filePaths: filePaths as any,
+      imagePath: storedImage?.path || undefined,
+      linkedMemoryIds,
+      pinned: pinned === true,
+      sharedWith: Array.isArray(sharedWith) ? sharedWith : undefined,
+    })
+    return `Stored memory "${key}" (id: ${entry.id})`
+  }
 
-            const normalizedLegacyRefs = Array.isArray(filePaths)
-              ? filePaths.map((f: any) => ({
-                  type: f.kind === 'project' ? 'project' : (f.kind === 'folder' ? 'folder' : 'file'),
-                  path: f.path,
-                  projectRoot: f.projectRoot,
-                  projectName: f.projectName,
-                  note: f.contextSnippet,
-                  timestamp: typeof f.timestamp === 'number' ? f.timestamp : Date.now(),
-                }))
-              : []
-            const normalizedRefs = Array.isArray(references) ? references : []
-            if (project?.rootPath) {
-              normalizedRefs.push({
-                type: 'project',
-                path: project.rootPath,
-                projectRoot: project.rootPath,
-                projectName: project.name,
-                title: project.name,
-                note: project.note,
-                timestamp: Date.now(),
-              })
-            }
-            const mergedRefs = [...normalizedLegacyRefs, ...normalizedRefs]
+  if (action === 'get') {
+    const found = memDb.get(key)
+    if (!found || !canReadMemory(found)) return `Memory not found or access denied: ${key}`
+    return formatEntry(found)
+  }
 
-            const formatEntry = (m: any) => {
-              let line = `[${m.id}] (${m.agentId ? `agent:${m.agentId}` : 'shared'}) ${m.category}/${m.title}: ${m.content}`
-              if (m.reinforcementCount) line += ` (reinforced ×${m.reinforcementCount})`
-              if (m.references?.length) {
-                line += `\n  refs: ${m.references.map((r: any) => {
-                  const core = r.path || r.title || r.type
-                  const projectMeta = r.projectName ? ` @${r.projectName}` : ''
-                  const existsMeta = typeof r.exists === 'boolean' ? (r.exists ? ' (exists)' : ' (missing)') : ''
-                  return `${r.type}:${core}${projectMeta}${existsMeta}`
-                }).join(', ')}`
-              } else if (m.filePaths?.length) {
-                line += `\n  files: ${m.filePaths.map((f: any) => `${f.path}${f.contextSnippet ? ` (${f.contextSnippet})` : ''}`).join(', ')}`
-              }
-              if (m.image?.path || m.imagePath) line += `\n  image: ${m.image?.path || m.imagePath}`
-              if (m.linkedMemoryIds?.length) line += `\n  linked: ${m.linkedMemoryIds.join(', ')}`
-              return line
-            }
+  if (action === 'search') {
+    const queries = query ? await expandQuery(query) : [key || '']
+    const allResults: MemoryEntry[] = []
+    const seenIds = new Set<string>()
+    for (const q of queries) {
+      const results = memDb.search(q, currentAgentId || undefined, { scope: scopeFilter, rerankMode })
+      for (const r of results) {
+        if (!seenIds.has(r.id)) {
+          seenIds.add(r.id); allResults.push(r)
+        }
+      }
+    }
+    if (!allResults.length) return 'No memories found.'
+    return allResults.slice(0, maxPerLookup).map(formatEntry).join('\n')
+  }
 
-            if (action === 'store') {
-              let storedImage: any = null
-              if (imagePath) {
-                if (!fs.existsSync(imagePath)) {
-                  return `Error: image file not found: ${imagePath}`
-                }
-                try {
-                  storedImage = await storeMemoryImageAsset(imagePath, genId(6))
-                } catch {
-                  return `Error: failed to process image at ${imagePath}`
-                }
-              }
+  if (action === 'list') {
+    const results = filterScope(memDb.list(undefined, maxPerLookup))
+    return results.length ? results.map(formatEntry).join('\n') : 'No memories stored yet.'
+  }
 
-              const entry = memDb.add({
-                agentId: scopeMode === 'shared' ? null : currentAgentId,
-                sessionId: ctx?.sessionId || null,
-                category: category || 'note',
-                title: key,
-                content: value || '',
-                references: mergedRefs as any,
-                filePaths: filePaths as any,
-                image: storedImage,
-                imagePath: storedImage?.path || undefined,
-                linkedMemoryIds,
-                pinned: pinned === true,
-                sharedWith: Array.isArray(sharedWith) ? sharedWith : undefined,
-              })
-              const memoryScope = entry.agentId ? 'agent' : 'shared'
-              let result = `Stored ${memoryScope} memory "${key}" (id: ${entry.id})`
-              if (mergedRefs.length) result += ` with ${mergedRefs.length} reference(s)`
-              if (storedImage?.path) result += ` with image`
-              if (linkedMemoryIds?.length) result += ` linked to ${linkedMemoryIds.length} memor${linkedMemoryIds.length === 1 ? 'y' : 'ies'}`
-              return result
-            }
-            if (action === 'get') {
-              if (effectiveDepth > 0) {
-                const result = memDb.getWithLinked(key, effectiveDepth, maxPerLookup, effectiveLinkedLimit)
-                if (!result) return `Memory not found: ${key}`
-                const accessible = result.entries.filter(canAccessMemory)
-                if (!accessible.length) return 'Error: you do not have access to that memory.'
-                let output = accessible.map(formatEntry).join('\n---\n')
-                if (result.truncated) output += `\n\n[Results truncated at ${maxPerLookup} memories / ${effectiveLinkedLimit} linked expansions]`
-                return output
-              }
-              const found = memDb.get(key)
-              if (!found) return `Memory not found: ${key}`
-              if (!canAccessMemory(found)) return 'Error: you do not have access to that memory.'
-              return formatEntry(found)
-            }
-            if (action === 'search') {
-              if (effectiveDepth > 0) {
-                const result = memDb.searchWithLinked(query || key, undefined, effectiveDepth, maxPerLookup, effectiveLinkedLimit)
-                const accessible = filterScope(result.entries)
-                if (!accessible.length) return 'No memories found.'
-                let output = accessible.map(formatEntry).join('\n')
-                if (result.truncated) output += `\n\n[Results truncated at ${maxPerLookup} memories / ${effectiveLinkedLimit} linked expansions]`
-                return output
-              }
-              const results = filterScope(memDb.search(query || key))
-              if (!results.length) return 'No memories found.'
-              return results.slice(0, maxPerLookup).map(formatEntry).join('\n')
-            }
-            if (action === 'list') {
-              const results = filterScope(memDb.list(undefined, maxPerLookup))
-              if (!results.length) return 'No memories stored yet.'
-              return results.map(formatEntry).join('\n')
-            }
-            if (action === 'delete') {
-              const found = memDb.get(key)
-              if (!found) return `Memory not found: ${key}`
-              if (!canAccessMemory(found)) return 'Error: you do not have access to that memory.'
-              memDb.delete(key)
-              return `Deleted memory "${key}"`
-            }
-            if (action === 'link') {
-              if (!targetIds?.length) return 'Error: targetIds required for link action.'
-              const result = memDb.link(key, targetIds, true)
-              if (!result) return `Memory not found: ${key}`
-              return `Linked memory "${key}" to ${targetIds.length} memor${targetIds.length === 1 ? 'y' : 'ies'} (bidirectional): ${targetIds.join(', ')}`
-            }
-            if (action === 'unlink') {
-              if (!targetIds?.length) return 'Error: targetIds required for unlink action.'
-              const result = memDb.unlink(key, targetIds, true)
-              if (!result) return `Memory not found: ${key}`
-              return `Unlinked ${targetIds.length} memor${targetIds.length === 1 ? 'y' : 'ies'} from "${key}" (bidirectional)`
-            }
-            if (action === 'knowledge_store') {
-              const { addKnowledge } = await import('../memory-db')
-              if (!value) return 'Error: value (content) is required for knowledge_store'
-              const source = (input as Record<string, unknown>).source as string | undefined
-              const sourceUrl = (input as Record<string, unknown>).sourceUrl as string | undefined
-              const entry = addKnowledge({
-                title: key || 'Untitled',
-                content: value,
-                tags: tags,
-                createdByAgentId: ctx?.agentId || null,
-                createdBySessionId: ctx?.sessionId || null,
-                source: source || undefined,
-                sourceUrl: sourceUrl || undefined,
-              })
-              return `Knowledge stored: "${entry.title}" (id: ${entry.id})`
-            }
-            if (action === 'knowledge_search') {
-              const { searchKnowledge } = await import('../memory-db')
-              const results = searchKnowledge(query || key || '', tags, 10)
-              if (!results.length) return 'No knowledge entries found.'
-              return results.map(r => {
-                const meta = r.metadata as Record<string, unknown> | undefined
-                const src = meta?.source as string | undefined
-                const srcUrl = meta?.sourceUrl as string | undefined
-                let line = `[${r.id}] ${r.title}: ${r.content.slice(0, 200)}`
-                if (src && srcUrl) {
-                  line += ` [${src}](${srcUrl})`
-                } else if (src) {
-                  line += ` (source: ${src})`
-                } else if (srcUrl) {
-                  line += ` (${srcUrl})`
-                }
-                return line
-              }).join('\n---\n')
-            }
-            return `Unknown action "${action}". Use: store, get, search, list, delete, link, unlink, knowledge_store, or knowledge_search.`
-          } catch (err: unknown) {
-            return `Error: ${err instanceof Error ? err.message : String(err)}`
-          }
-        },
-        {
-          name: 'memory_tool',
-          description: 'My long-term memory — things I remember across conversations. I can store personal notes, recall past context, and build up knowledge over time. Memories can be private to me or shared with other agents. I can also attach files, link related memories, and contribute to a shared knowledge base. Actions: store, get, search, list, delete, link, unlink, knowledge_store, knowledge_search.',
-          schema: z.object({
-            action: z.enum(['store', 'get', 'search', 'list', 'delete', 'link', 'unlink', 'knowledge_store', 'knowledge_search']).describe('The action to perform'),
-            key: z.string().describe('For store: memory title. For get/delete/link/unlink: memory ID. For search: optional query fallback.'),
-            value: z.string().optional().describe('The memory content (for store action)'),
-            category: z.string().optional().describe('Category like "note", "fact", "preference", "project", "identity" (for store action, defaults to "note")'),
-            query: z.string().optional().describe('Search query (alternative to key for search action)'),
-            scope: z.enum(['auto', 'shared', 'agent']).optional().describe('Scope hint: auto (shared + own), shared, or agent'),
-            filePaths: z.array(z.object({
-              path: z.string().describe('File or folder path'),
-              contextSnippet: z.string().optional().describe('Brief context about this file reference'),
-              kind: z.enum(['file', 'folder', 'project']).optional().describe('Reference type for legacy filePaths compatibility'),
-              projectRoot: z.string().optional().describe('Optional project root path'),
-              projectName: z.string().optional().describe('Optional project display name'),
-              exists: z.boolean().optional().describe('Optional known existence state'),
-              timestamp: z.number().describe('When this file was referenced'),
-            })).optional().describe('File/folder references to attach to the memory (for store action)'),
-            references: z.array(z.object({
-              type: z.enum(['project', 'folder', 'file', 'task', 'session', 'url']),
-              path: z.string().optional(),
-              projectRoot: z.string().optional(),
-              projectName: z.string().optional(),
-              title: z.string().optional(),
-              note: z.string().optional(),
-              timestamp: z.number().optional(),
-            })).optional().describe('Structured references attached to the memory (preferred over filePaths).'),
-            project: z.object({
-              rootPath: z.string().describe('Project/workspace root path'),
-              name: z.string().optional().describe('Optional project display name'),
-              note: z.string().optional().describe('Optional note about the project context'),
-            }).optional().describe('Shortcut to add a project reference on store action.'),
-            imagePath: z.string().optional().describe('Path to an image file to attach (will be compressed and stored). For store action.'),
-            linkedMemoryIds: z.array(z.string()).optional().describe('IDs of other memories to link to (for store action)'),
-            depth: z.number().optional().describe('How deep to traverse linked memories (for get/search). Respects configured maxDepth limit. Default: 0 (no traversal).'),
-            linkedLimit: z.number().optional().describe('Max linked memories expanded during traversal. Respects configured server cap.'),
-            targetIds: z.array(z.string()).optional().describe('Memory IDs to link/unlink (for link/unlink actions)'),
-            tags: z.array(z.string()).optional().describe('Tags for categorizing knowledge entries'),
-            source: z.string().optional().describe("Source of the knowledge, e.g. 'user', 'web', 'document'"),
-            sourceUrl: z.string().optional().describe('URL where the knowledge was sourced from'),
-            pinned: z.boolean().optional().describe('Mark memory as pinned (always preloaded in agent context). For store action.'),
-            sharedWith: z.array(z.string()).optional().describe('Agent IDs to share this memory with (for store action). They can read it in their context.'),
-          }),
-        },
-      ),
-    )
+  if (action === 'delete') {
+    const found = memDb.get(key)
+    if (!found || !canMutateMemory(found)) return 'Memory not found or access denied.'
+    memDb.delete(key)
+    return `Deleted memory "${key}"`
   }
 
-  return tools
+  return `Unknown action "${action}".`
+}
+
+/**
+ * Register as a Built-in Plugin
+ */
+const MemoryPlugin: Plugin = {
+  name: 'Core Memory',
+  description: 'Advanced database-backed long-term memory with semantic search and graph linking.',
+  hooks: {} as PluginHooks,
+  tools: [
+    {
+      name: 'memory_tool',
+      description: 'Advanced long-term memory system. Use to store and recall facts across all conversations.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['store', 'get', 'search', 'list', 'delete'] },
+          key: { type: 'string' },
+          value: { type: 'string' },
+          category: { type: 'string' },
+          query: { type: 'string' },
+          scope: { type: 'string', enum: ['auto', 'all', 'global', 'shared', 'agent', 'session', 'project'] },
+        },
+        required: ['action']
+      },
+      execute: async (args, context) => {
+        return executeMemoryAction(args, context.session)
+      }
+    }
+  ]
+}
+
+// Auto-register when imported
+getPluginManager().registerBuiltin('memory', MemoryPlugin)
+
+export function buildMemoryTools(bctx: ToolBuildContext) {
+  if (!bctx.hasTool('memory')) return []
+  
+  return [
+    tool(
+      async (args) => executeMemoryAction(args, bctx.ctx),
+      {
+        name: 'memory_tool',
+        description: MemoryPlugin.tools![0].description,
+        schema: z.object({}).passthrough()
+      }
+    )
+  ]
 }

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

@@ -0,0 +1,126 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import fs from 'fs'
+import path from 'path'
+import * as os from 'os'
+import type { ToolBuildContext } from './context'
+import { getPluginManager } from '../plugins'
+import type { Plugin, PluginHooks } from '@/types'
+import { safePath, truncate } from './context'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+
+/**
+ * Unified Monitoring Logic
+ */
+async function executeMonitorAction(args: any, bctx: { cwd: string }) {
+  const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
+  const action = normalized.action as string | undefined
+  const target = (normalized.target ?? normalized.url ?? normalized.path) as string | undefined
+  const limit = normalized.limit as number | undefined
+  const threshold = normalized.threshold as number | undefined
+
+  try {
+    switch (action) {
+      case 'sys_info': {
+        const freeMem = os.freemem()
+        const totalMem = os.totalmem()
+        const load = os.loadavg()
+        const uptime = os.uptime()
+        return JSON.stringify({
+          platform: os.platform(),
+          arch: os.arch(),
+          cpus: os.cpus().length,
+          memory: {
+            free: `${Math.round(freeMem / 1024 / 1024)}MB`,
+            total: `${Math.round(totalMem / 1024 / 1024)}MB`,
+            usage: `${Math.round(((totalMem - freeMem) / totalMem) * 100)}%`
+          },
+          loadAvg: load,
+          uptime: `${Math.round(uptime / 3600)} hours`
+        }, null, 2)
+      }
+
+      case 'watch_log': {
+        const resolved = safePath(bctx.cwd, target!)
+        if (!fs.existsSync(resolved)) return `Error: File not found ${target}`
+        
+        const stats = fs.statSync(resolved)
+        const size = stats.size
+        const bufferSize = Math.min(size, 5000) // Read last 5KB
+        const fd = fs.openSync(resolved, 'r')
+        const buffer = Buffer.alloc(bufferSize)
+        fs.readSync(fd, buffer, 0, bufferSize, size - bufferSize)
+        fs.closeSync(fd)
+        
+        return truncate(buffer.toString('utf8'), 2000)
+      }
+
+      case 'ping': {
+        const url = target?.startsWith('http') ? target : `http://${target}`
+        const start = Date.now()
+        try {
+          const res = await fetch(url, { signal: AbortSignal.timeout(5000) })
+          const latency = Date.now() - start
+          return JSON.stringify({
+            status: res.status,
+            ok: res.ok,
+            latency: `${latency}ms`,
+            url
+          }, null, 2)
+        } catch (err: any) {
+          return JSON.stringify({
+            status: 'error',
+            error: err.message,
+            url
+          }, null, 2)
+        }
+      }
+
+      default:
+        return `Error: Unknown action "${action}"`
+    }
+  } catch (err: any) {
+    return `Error: ${err.message}`
+  }
+}
+
+/**
+ * Register as a Built-in Plugin
+ */
+const MonitorPlugin: Plugin = {
+  name: 'Core Monitor',
+  description: 'System observability: check resource usage, watch logs, and ping endpoints.',
+  hooks: {} as PluginHooks,
+  tools: [
+    {
+      name: 'monitor_tool',
+      description: 'Observe system health, log activity, or endpoint availability.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['sys_info', 'watch_log', 'ping'] },
+          target: { type: 'string', description: 'Log file path (for watch_log) or URL (for ping)' },
+          limit: { type: 'number', description: 'Number of lines or bytes to retrieve' }
+        },
+        required: ['action']
+      },
+      execute: async (args, context) => executeMonitorAction(args, { cwd: context.session.cwd || process.cwd() })
+    }
+  ]
+}
+
+getPluginManager().registerBuiltin('monitor', MonitorPlugin)
+
+export function buildMonitorTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasTool('monitor')) return []
+  return [
+    tool(
+      async (args) => executeMonitorAction(args, { cwd: bctx.cwd }),
+      {
+        name: 'monitor_tool',
+        description: MonitorPlugin.tools![0].description,
+        schema: z.object({}).passthrough()
+      }
+    )
+  ]
+}

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

@@ -0,0 +1,61 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+
+describe('normalizeToolInputArgs', () => {
+  it('keeps top-level args as-is when there is no wrapper', () => {
+    const out = normalizeToolInputArgs({ action: 'list', path: '/tmp' })
+    assert.equal(out.action, 'list')
+    assert.equal(out.path, '/tmp')
+  })
+
+  it('merges nested input object payloads', () => {
+    const out = normalizeToolInputArgs({
+      input: {
+        action: 'execute',
+        execute_command: 'pwd',
+      },
+    })
+    assert.equal(out.action, 'execute')
+    assert.equal(out.execute_command, 'pwd')
+  })
+
+  it('merges stringified input payloads', () => {
+    const out = normalizeToolInputArgs({
+      input: JSON.stringify({
+        action: 'list',
+        path: '/Users/dev/project',
+      }),
+    })
+    assert.equal(out.action, 'list')
+    assert.equal(out.path, '/Users/dev/project')
+  })
+
+  it('supports args/payload wrapper aliases', () => {
+    const out = normalizeToolInputArgs({
+      args: { action: 'read', filePath: 'README.md' },
+      payload: { limit: 10 },
+    })
+    assert.equal(out.action, 'read')
+    assert.equal(out.filePath, 'README.md')
+    assert.equal(out.limit, 10)
+  })
+
+  it('keeps explicit top-level values over nested wrappers', () => {
+    const out = normalizeToolInputArgs({
+      action: 'top-level',
+      input: { action: 'nested' },
+    })
+    assert.equal(out.action, 'top-level')
+  })
+
+  it('preserves falsey top-level values', () => {
+    const out = normalizeToolInputArgs({
+      input: { limit: 5, approved: true },
+      limit: 0,
+      approved: false,
+    })
+    assert.equal(out.limit, 0)
+    assert.equal(out.approved, false)
+  })
+})

package/src/lib/server/session-tools/normalize-tool-args.ts

@@ -0,0 +1,48 @@
+export type ToolArgsRecord = Record<string, unknown>
+
+function parseRecordCandidate(value: unknown): ToolArgsRecord | null {
+  if (!value) return null
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    return value as ToolArgsRecord
+  }
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed || (!trimmed.startsWith('{') && !trimmed.startsWith('['))) return null
+  try {
+    const parsed = JSON.parse(trimmed)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as ToolArgsRecord
+    }
+  } catch {
+    // ignore non-JSON strings
+  }
+  return null
+}
+
+/**
+ * Normalize common wrapper payloads used by older tool callers.
+ *
+ * Supports payloads nested under `input`, `args`, `arguments`, or `payload`
+ * as either objects or JSON strings.
+ */
+export function normalizeToolInputArgs(rawArgs: ToolArgsRecord): ToolArgsRecord {
+  const nestedSources: Array<ToolArgsRecord | null> = [
+    parseRecordCandidate(rawArgs.input),
+    parseRecordCandidate(rawArgs.args),
+    parseRecordCandidate(rawArgs.arguments),
+    parseRecordCandidate(rawArgs.payload),
+  ]
+
+  const normalized: ToolArgsRecord = {}
+  for (const nested of nestedSources) {
+    if (!nested) continue
+    Object.assign(normalized, nested)
+  }
+
+  for (const [key, value] of Object.entries(rawArgs)) {
+    if (value === undefined || value === null) continue
+    normalized[key] = value
+  }
+
+  return normalized
+}