@swarmclawai/swarmclaw 0.6.8 → 0.7.0

package/src/lib/server/llm-response-cache.test.ts

@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type { Message } from '@/types'
+import {
+  buildLlmResponseCacheKey,
+  clearLlmResponseCache,
+  getCachedLlmResponse,
+  resolveLlmResponseCacheConfig,
+  setCachedLlmResponse,
+} from './llm-response-cache.ts'
+
+const HISTORY: Message[] = [
+  { role: 'user', text: 'Plan a release.', time: 1 },
+  { role: 'assistant', text: 'Drafted plan.', time: 2 },
+]
+
+test('buildLlmResponseCacheKey is deterministic for equivalent payloads', () => {
+  const keyA = buildLlmResponseCacheKey({
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    apiEndpoint: 'https://api.openai.com/v1',
+    systemPrompt: 'System prompt',
+    message: 'hello',
+    history: HISTORY,
+    attachedFiles: ['a.txt', 'b.txt'],
+  })
+  const keyB = buildLlmResponseCacheKey({
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    apiEndpoint: 'https://api.openai.com/v1',
+    systemPrompt: '  System   prompt ',
+    message: 'hello',
+    history: [...HISTORY],
+    attachedFiles: ['a.txt', 'b.txt'],
+  })
+  assert.equal(keyA, keyB)
+})
+
+test('set/get cached responses returns hit and increments hit count', () => {
+  clearLlmResponseCache()
+  const config = { enabled: true, ttlMs: 60_000, maxEntries: 10 }
+  const keyInput = {
+    provider: 'openai',
+    model: 'gpt-4o',
+    message: 'status',
+    history: HISTORY,
+  }
+  setCachedLlmResponse(keyInput, 'cached answer', config, 1000)
+  const hit1 = getCachedLlmResponse(keyInput, config, 1500)
+  assert.ok(hit1)
+  assert.equal(hit1?.text, 'cached answer')
+  assert.equal(hit1?.hits, 1)
+  const hit2 = getCachedLlmResponse(keyInput, config, 1600)
+  assert.equal(hit2?.hits, 2)
+})
+
+test('expired cache entry is not returned', () => {
+  clearLlmResponseCache()
+  const config = { enabled: true, ttlMs: 1000, maxEntries: 10 }
+  const keyInput = {
+    provider: 'openai',
+    model: 'gpt-4o',
+    message: 'status',
+    history: HISTORY,
+  }
+  setCachedLlmResponse(keyInput, 'stale', config, 1000)
+  const miss = getCachedLlmResponse(keyInput, config, 3001)
+  assert.equal(miss, null)
+})
+
+test('cache evicts least recently used entries over maxEntries', () => {
+  clearLlmResponseCache()
+  const config = { enabled: true, ttlMs: 60_000, maxEntries: 2 }
+  const inputA = { provider: 'openai', model: 'gpt-4o', message: 'a', history: HISTORY }
+  const inputB = { provider: 'openai', model: 'gpt-4o', message: 'b', history: HISTORY }
+  const inputC = { provider: 'openai', model: 'gpt-4o', message: 'c', history: HISTORY }
+  setCachedLlmResponse(inputA, 'A', config, 1000)
+  setCachedLlmResponse(inputB, 'B', config, 1001)
+  // Touch A so B becomes LRU.
+  getCachedLlmResponse(inputA, config, 1002)
+  setCachedLlmResponse(inputC, 'C', config, 1003)
+
+  assert.equal(getCachedLlmResponse(inputB, config, 1004), null)
+  assert.equal(getCachedLlmResponse(inputA, config, 1004)?.text, 'A')
+  assert.equal(getCachedLlmResponse(inputC, config, 1004)?.text, 'C')
+})
+
+test('resolveLlmResponseCacheConfig applies defaults and bounds', () => {
+  const fallback = resolveLlmResponseCacheConfig({})
+  assert.equal(fallback.enabled, true)
+  assert.equal(fallback.ttlMs, 900_000)
+  assert.equal(fallback.maxEntries, 500)
+
+  const custom = resolveLlmResponseCacheConfig({
+    responseCacheEnabled: false,
+    responseCacheTtlSec: 1,
+    responseCacheMaxEntries: 999999,
+  })
+  assert.equal(custom.enabled, false)
+  assert.equal(custom.ttlMs, 5000)
+  assert.equal(custom.maxEntries, 20_000)
+})

package/src/lib/server/llm-response-cache.ts

@@ -0,0 +1,227 @@
+import crypto from 'node:crypto'
+import type { AppSettings, Message } from '@/types'
+
+export interface LlmResponseCacheConfig {
+  enabled: boolean
+  ttlMs: number
+  maxEntries: number
+}
+
+export interface LlmResponseCacheKeyInput {
+  provider: string
+  model: string
+  apiEndpoint?: string | null
+  systemPrompt?: string
+  message: string
+  imagePath?: string
+  imageUrl?: string
+  attachedFiles?: string[]
+  history: Message[]
+}
+
+export interface LlmResponseCacheHit {
+  key: string
+  text: string
+  provider: string
+  model: string
+  createdAt: number
+  ageMs: number
+  hits: number
+}
+
+interface LlmResponseCacheEntry {
+  key: string
+  text: string
+  provider: string
+  model: string
+  createdAt: number
+  expiresAt: number
+  hits: number
+}
+
+const DEFAULT_ENABLED = true
+const DEFAULT_TTL_SEC = 15 * 60
+const DEFAULT_MAX_ENTRIES = 500
+
+const MIN_TTL_SEC = 5
+const MAX_TTL_SEC = 7 * 24 * 3600
+const MIN_ENTRIES = 1
+const MAX_ENTRIES = 20_000
+
+const responseCache = new Map<string, LlmResponseCacheEntry>()
+
+function normalizeText(value: unknown): string {
+  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : ''
+}
+
+function normalizeList(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+function normalizeInt(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number.parseInt(value, 10)
+      : Number.NaN
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+function normalizeBool(value: unknown, fallback: boolean): boolean {
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+    if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  }
+  return fallback
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null) return 'null'
+  const kind = typeof value
+  if (kind === 'number' || kind === 'boolean') return JSON.stringify(value)
+  if (kind === 'string') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(',')}]`
+  if (kind === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
+  }
+  return JSON.stringify(String(value))
+}
+
+function normalizeHistory(history: Message[]): Array<Record<string, unknown>> {
+  return history.map((entry) => ({
+    role: entry.role,
+    text: normalizeText(entry.text),
+    kind: entry.kind || null,
+    imagePath: entry.imagePath || null,
+    imageUrl: entry.imageUrl || null,
+    attachedFiles: normalizeList(entry.attachedFiles),
+    replyToId: entry.replyToId || null,
+  }))
+}
+
+function trimToCapacity(maxEntries: number): void {
+  while (responseCache.size > maxEntries) {
+    const oldestKey = responseCache.keys().next().value as string | undefined
+    if (!oldestKey) break
+    responseCache.delete(oldestKey)
+  }
+}
+
+function moveToMostRecent(key: string, entry: LlmResponseCacheEntry): void {
+  responseCache.delete(key)
+  responseCache.set(key, entry)
+}
+
+export function resolveLlmResponseCacheConfig(
+  settings?: AppSettings | Record<string, unknown> | null,
+): LlmResponseCacheConfig {
+  const raw = settings && typeof settings === 'object' ? settings as Record<string, unknown> : {}
+  const ttlSec = normalizeInt(raw.responseCacheTtlSec, DEFAULT_TTL_SEC, MIN_TTL_SEC, MAX_TTL_SEC)
+  const maxEntries = normalizeInt(raw.responseCacheMaxEntries, DEFAULT_MAX_ENTRIES, MIN_ENTRIES, MAX_ENTRIES)
+  const enabled = normalizeBool(raw.responseCacheEnabled, DEFAULT_ENABLED)
+  return {
+    enabled,
+    ttlMs: ttlSec * 1000,
+    maxEntries,
+  }
+}
+
+export function buildLlmResponseCacheKey(input: LlmResponseCacheKeyInput): string {
+  const payload = {
+    provider: normalizeText(input.provider).toLowerCase(),
+    model: normalizeText(input.model),
+    apiEndpoint: normalizeText(input.apiEndpoint || ''),
+    systemPrompt: normalizeText(input.systemPrompt || ''),
+    message: normalizeText(input.message),
+    imagePath: normalizeText(input.imagePath || ''),
+    imageUrl: normalizeText(input.imageUrl || ''),
+    attachedFiles: normalizeList(input.attachedFiles),
+    history: normalizeHistory(Array.isArray(input.history) ? input.history : []),
+  }
+  const stable = stableStringify(payload)
+  return crypto.createHash('sha256').update(stable).digest('hex')
+}
+
+export function getCachedLlmResponse(
+  input: LlmResponseCacheKeyInput,
+  config: LlmResponseCacheConfig,
+  now = Date.now(),
+): LlmResponseCacheHit | null {
+  if (!config.enabled) return null
+  const key = buildLlmResponseCacheKey(input)
+  const found = responseCache.get(key)
+  if (!found) return null
+  if (now >= found.expiresAt) {
+    responseCache.delete(key)
+    return null
+  }
+  const next = { ...found, hits: found.hits + 1 }
+  moveToMostRecent(key, next)
+  return {
+    key,
+    text: next.text,
+    provider: next.provider,
+    model: next.model,
+    createdAt: next.createdAt,
+    ageMs: Math.max(0, now - next.createdAt),
+    hits: next.hits,
+  }
+}
+
+export function setCachedLlmResponse(
+  input: LlmResponseCacheKeyInput,
+  text: string,
+  config: LlmResponseCacheConfig,
+  now = Date.now(),
+): void {
+  if (!config.enabled) return
+  const normalizedText = normalizeText(text)
+  if (!normalizedText) return
+  const key = buildLlmResponseCacheKey(input)
+  const existing = responseCache.get(key)
+  const createdAt = existing?.createdAt ?? now
+  const entry: LlmResponseCacheEntry = {
+    key,
+    text: normalizedText,
+    provider: normalizeText(input.provider).toLowerCase(),
+    model: normalizeText(input.model),
+    createdAt,
+    expiresAt: now + config.ttlMs,
+    hits: existing?.hits ?? 0,
+  }
+  moveToMostRecent(key, entry)
+  trimToCapacity(config.maxEntries)
+}
+
+export function getLlmResponseCacheStats(now = Date.now()): {
+  entries: number
+  expired: number
+  oldestAgeMs: number
+} {
+  let expired = 0
+  let oldestCreatedAt = Number.POSITIVE_INFINITY
+  for (const entry of responseCache.values()) {
+    if (entry.expiresAt <= now) expired++
+    oldestCreatedAt = Math.min(oldestCreatedAt, entry.createdAt)
+  }
+  const oldestAgeMs = Number.isFinite(oldestCreatedAt) ? Math.max(0, now - oldestCreatedAt) : 0
+  return {
+    entries: responseCache.size,
+    expired,
+    oldestAgeMs,
+  }
+}
+
+export function clearLlmResponseCache(): void {
+  responseCache.clear()
+}

package/src/lib/server/main-agent-loop.ts

@@ -935,7 +935,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   const sessions = loadSessions()
   const session = sessions[input.sessionId]
   if (!session) return null
-  if (!isMainSession(session)) return handleAgentHeartbeatResult(session, input)
+  if (!isProtectedMainSession(session)) return handleAgentHeartbeatResult(session, input)
 
   const now = Date.now()
   const state = normalizeState(session.mainLoopState, now)

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

@@ -3,12 +3,15 @@ const MAIN_SESSION_NAME = '__main__'
 export function isProtectedMainSession(session: any): boolean {
   if (!session || typeof session !== 'object') return false
   if (session.mainSession === true) return true
-
-  const name = typeof session.name === 'string' ? session.name.trim() : ''
-  if (name === MAIN_SESSION_NAME) return true
+  if (session.sessionType === 'orchestrated') return true
 
   const id = typeof session.id === 'string' ? session.id.trim() : ''
   if (id.startsWith('main-')) return true
+  if (id.startsWith('agent-thread-')) return true
+
+  const name = typeof session.name === 'string' ? session.name.trim() : ''
+  if (name === MAIN_SESSION_NAME) return true
+  if (name.startsWith('agent-thread:')) return true
 
   return false
 }

package/src/lib/server/mcp-conformance.test.ts

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { runMcpConformanceCheck } from './mcp-conformance.ts'
+
+test('runMcpConformanceCheck reports connect/list failure for unsupported transport', async () => {
+  const result = await runMcpConformanceCheck({
+    id: 'bad',
+    name: 'Bad MCP',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transport: 'invalid-transport' as any,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  })
+
+  assert.equal(result.ok, false)
+  assert.equal(result.toolsCount, 0)
+  assert.ok(result.issues.some((issue) => issue.code === 'connect_or_list_failed'))
+})

package/src/lib/server/mcp-conformance.ts

@@ -0,0 +1,233 @@
+import type { McpServerConfig } from '@/types'
+import { connectMcpServer, disconnectMcpServer } from './mcp-client'
+
+export interface McpConformanceIssue {
+  level: 'error' | 'warning'
+  code: string
+  message: string
+  toolName?: string
+}
+
+export interface McpConformanceOptions {
+  timeoutMs?: number
+  smokeToolName?: string | null
+  smokeToolArgs?: Record<string, unknown> | null
+}
+
+export interface McpConformanceResult {
+  ok: boolean
+  serverId: string
+  serverName: string
+  checkedAt: number
+  toolsCount: number
+  smokeToolName: string | null
+  issues: McpConformanceIssue[]
+  timings: {
+    connectMs: number
+    listToolsMs: number
+    smokeInvokeMs: number | null
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 12_000
+const MIN_TIMEOUT_MS = 1_000
+const MAX_TIMEOUT_MS = 120_000
+
+function normalizeTimeoutMs(value: unknown): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number.parseInt(value, 10)
+      : Number.NaN
+  if (!Number.isFinite(parsed)) return DEFAULT_TIMEOUT_MS
+  return Math.max(MIN_TIMEOUT_MS, Math.min(MAX_TIMEOUT_MS, Math.trunc(parsed)))
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function normalizedRequired(schema: Record<string, unknown>): string[] {
+  const required = schema.required
+  if (!Array.isArray(required)) return []
+  return required.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function findSmokeTool(tools: Array<Record<string, unknown>>, preferredName?: string | null): string | null {
+  const preferred = typeof preferredName === 'string' ? preferredName.trim() : ''
+  if (preferred) {
+    const found = tools.find((tool) => tool.name === preferred)
+    if (found) return preferred
+  }
+
+  const noArg = tools.find((tool) => {
+    const schema = isRecord(tool.inputSchema) ? tool.inputSchema : {}
+    const required = normalizedRequired(schema)
+    return required.length === 0
+  })
+  if (noArg && typeof noArg.name === 'string' && noArg.name.trim()) return noArg.name
+  return null
+}
+
+function validateToolSchemas(tools: Array<Record<string, unknown>>, issues: McpConformanceIssue[]): void {
+  const seenNames = new Set<string>()
+  for (const tool of tools) {
+    const toolName = typeof tool.name === 'string' ? tool.name.trim() : ''
+    if (!toolName) {
+      issues.push({
+        level: 'error',
+        code: 'tool_name_missing',
+        message: 'Tool is missing a valid name.',
+      })
+      continue
+    }
+    if (seenNames.has(toolName)) {
+      issues.push({
+        level: 'error',
+        code: 'tool_name_duplicate',
+        message: `Duplicate tool name "${toolName}" detected.`,
+        toolName,
+      })
+      continue
+    }
+    seenNames.add(toolName)
+
+    const schema = isRecord(tool.inputSchema) ? tool.inputSchema : null
+    if (!schema) {
+      issues.push({
+        level: 'warning',
+        code: 'tool_schema_missing',
+        message: `Tool "${toolName}" is missing an input schema.`,
+        toolName,
+      })
+      continue
+    }
+
+    const schemaType = typeof schema.type === 'string' ? schema.type : 'object'
+    if (schemaType !== 'object') {
+      issues.push({
+        level: 'warning',
+        code: 'tool_schema_non_object',
+        message: `Tool "${toolName}" schema type is "${schemaType}" (expected "object").`,
+        toolName,
+      })
+    }
+
+    const properties = isRecord(schema.properties) ? schema.properties : {}
+    const required = normalizedRequired(schema)
+    for (const req of required) {
+      if (!Object.prototype.hasOwnProperty.call(properties, req)) {
+        issues.push({
+          level: 'warning',
+          code: 'tool_schema_required_missing_property',
+          message: `Tool "${toolName}" marks "${req}" as required but it is not present in schema.properties.`,
+          toolName,
+        })
+      }
+    }
+  }
+}
+
+export async function runMcpConformanceCheck(
+  server: McpServerConfig,
+  options: McpConformanceOptions = {},
+): Promise<McpConformanceResult> {
+  const timeoutMs = normalizeTimeoutMs(options.timeoutMs)
+  const issues: McpConformanceIssue[] = []
+  const checkedAt = Date.now()
+  const result: McpConformanceResult = {
+    ok: false,
+    serverId: server.id,
+    serverName: server.name,
+    checkedAt,
+    toolsCount: 0,
+    smokeToolName: null,
+    issues,
+    timings: {
+      connectMs: 0,
+      listToolsMs: 0,
+      smokeInvokeMs: null,
+    },
+  }
+
+  let client: unknown
+  let transport: unknown
+  const connectStart = Date.now()
+  try {
+    const conn = await withTimeout(connectMcpServer(server), timeoutMs, 'MCP connect')
+    client = conn.client
+    transport = conn.transport
+    result.timings.connectMs = Date.now() - connectStart
+
+    const mcpClient = client as { listTools: () => Promise<Record<string, unknown>>; callTool: (opts: Record<string, unknown>) => Promise<unknown> }
+    const listStart = Date.now()
+    const listResponse = await withTimeout(mcpClient.listTools(), timeoutMs, 'MCP listTools') as Record<string, unknown>
+    result.timings.listToolsMs = Date.now() - listStart
+    const tools = Array.isArray(listResponse?.tools) ? listResponse.tools as Array<Record<string, unknown>> : []
+    result.toolsCount = tools.length
+
+    validateToolSchemas(tools, issues)
+
+    const smokeToolName = findSmokeTool(tools, options.smokeToolName)
+    result.smokeToolName = smokeToolName
+    if (!smokeToolName) {
+      issues.push({
+        level: 'warning',
+        code: 'smoke_tool_missing',
+        message: 'No smoke-testable tool found (no no-arg tool and no explicit smokeToolName).',
+      })
+    } else {
+      const smokeArgs = options.smokeToolArgs && isRecord(options.smokeToolArgs)
+        ? options.smokeToolArgs
+        : {}
+      const smokeStart = Date.now()
+      try {
+        await withTimeout(
+          mcpClient.callTool({ name: smokeToolName, arguments: smokeArgs }),
+          timeoutMs,
+          `MCP callTool(${smokeToolName})`,
+        )
+      } catch (err) {
+        issues.push({
+          level: 'error',
+          code: 'smoke_tool_failed',
+          message: err instanceof Error ? err.message : String(err),
+          toolName: smokeToolName,
+        })
+      } finally {
+        result.timings.smokeInvokeMs = Date.now() - smokeStart
+      }
+    }
+  } catch (err) {
+    issues.push({
+      level: 'error',
+      code: 'connect_or_list_failed',
+      message: err instanceof Error ? err.message : String(err),
+    })
+  } finally {
+    if (client && transport) {
+      await disconnectMcpServer(client, transport)
+    }
+  }
+
+  result.ok = issues.every((issue) => issue.level !== 'error')
+  return result
+}