@swarmclawai/swarmclaw 0.2.0

package/src/lib/server/memory-graph.test.ts

@@ -0,0 +1,153 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import {
+  normalizeLinkedMemoryIds,
+  normalizeMemoryLookupLimits,
+  resolveLookupRequest,
+  traverseLinkedMemoryGraph,
+} from './memory-graph.ts'
+import type { MemoryLookupLimits, LinkedMemoryNode } from './memory-graph.ts'
+
+describe('normalizeLinkedMemoryIds', () => {
+  it('filters empty strings and self-references', () => {
+    assert.deepStrictEqual(
+      normalizeLinkedMemoryIds(['a', '', 'b', '  ', 'a', 'c'], 'self'),
+      ['a', 'b', 'c']
+    )
+  })
+
+  it('returns empty array for non-array input', () => {
+    assert.deepStrictEqual(normalizeLinkedMemoryIds(null), [])
+    assert.deepStrictEqual(normalizeLinkedMemoryIds(undefined), [])
+    assert.deepStrictEqual(normalizeLinkedMemoryIds('not-an-array'), [])
+  })
+
+  it('deduplicates ids', () => {
+    assert.deepStrictEqual(
+      normalizeLinkedMemoryIds(['a', 'b', 'a', 'a', 'c'], undefined),
+      ['a', 'b', 'c']
+    )
+  })
+})
+
+describe('normalizeMemoryLookupLimits', () => {
+  it('returns defaults for empty settings', () => {
+    const limits = normalizeMemoryLookupLimits({})
+    assert.strictEqual(limits.maxDepth, 3)
+    assert.strictEqual(limits.maxPerLookup, 20)
+    assert.strictEqual(limits.maxLinkedExpansion, 60)
+  })
+
+  it('clamps to valid ranges', () => {
+    const limits = normalizeMemoryLookupLimits({
+      memoryReferenceDepth: 100,
+      maxMemoriesPerLookup: 1000,
+      maxLinkedMemoriesExpanded: 5000,
+    })
+    assert.strictEqual(limits.maxDepth, 12) // max
+    assert.strictEqual(limits.maxPerLookup, 200) // max
+    assert.strictEqual(limits.maxLinkedExpansion, 1000) // max
+  })
+
+  it('allows zeros for depth and linked expansion', () => {
+    const limits = normalizeMemoryLookupLimits({
+      memoryReferenceDepth: 0,
+      maxMemoriesPerLookup: 5,
+      maxLinkedMemoriesExpanded: 0,
+    })
+    assert.strictEqual(limits.maxDepth, 0)
+    assert.strictEqual(limits.maxPerLookup, 5)
+    assert.strictEqual(limits.maxLinkedExpansion, 0)
+  })
+})
+
+describe('resolveLookupRequest', () => {
+  const defaults: MemoryLookupLimits = {
+    maxDepth: 3,
+    maxPerLookup: 20,
+    maxLinkedExpansion: 60,
+  }
+
+  it('uses defaults for empty request', () => {
+    assert.deepStrictEqual(resolveLookupRequest(defaults, {}), defaults)
+  })
+
+  it('overrides with request values', () => {
+    const result = resolveLookupRequest(defaults, { depth: 2, limit: 10, linkedLimit: 30 })
+    assert.strictEqual(result.maxDepth, 2)
+    assert.strictEqual(result.maxPerLookup, 10)
+    assert.strictEqual(result.maxLinkedExpansion, 30)
+  })
+
+  it('caps at defaults maxima', () => {
+    const result = resolveLookupRequest(defaults, { depth: 100, limit: 1000, linkedLimit: 5000 })
+    assert.strictEqual(result.maxDepth, 3)
+    assert.strictEqual(result.maxPerLookup, 20)
+    assert.strictEqual(result.maxLinkedExpansion, 60)
+  })
+})
+
+describe('traverseLinkedMemoryGraph', () => {
+  const fetchByIds = (ids: string[]): LinkedMemoryNode[] => {
+    return ids.map((id) => ({
+      id,
+      linkedMemoryIds: id === 'a' ? ['b', 'c'] : id === 'b' ? ['d'] : [],
+    }))
+  }
+
+  it('returns empty for empty seeds', () => {
+    const result = traverseLinkedMemoryGraph([], { maxDepth: 3, maxPerLookup: 20, maxLinkedExpansion: 60 }, fetchByIds)
+    assert.strictEqual(result.entries.length, 0)
+    assert.strictEqual(result.truncated, false)
+    assert.strictEqual(result.expandedLinkedCount, 0)
+  })
+
+  it('traverses linked nodes by depth', () => {
+    const seeds = [{ id: 'a', linkedMemoryIds: ['b', 'c'] }]
+    const result = traverseLinkedMemoryGraph(seeds, { maxDepth: 2, maxPerLookup: 20, maxLinkedExpansion: 60 }, fetchByIds)
+    const ids = result.entries.map((n) => n.id)
+    assert.ok(ids.includes('a'))
+    assert.ok(ids.includes('b'))
+    assert.ok(ids.includes('c'))
+    assert.ok(ids.includes('d')) // depth 2
+    assert.strictEqual(result.expandedLinkedCount, 3) // b, c, d
+  })
+
+  it('respects maxDepth', () => {
+    const limitedFetch = (ids: string[]): LinkedMemoryNode[] => {
+      const map: Record<string, string[]> = { a: ['b'], b: ['c'], c: ['d'], d: [] }
+      return ids.map((id) => ({ id, linkedMemoryIds: map[id] || [] }))
+    }
+    const seeds = [{ id: 'a', linkedMemoryIds: ['b'] }]
+    const result = traverseLinkedMemoryGraph(seeds, { maxDepth: 1, maxPerLookup: 20, maxLinkedExpansion: 60 }, limitedFetch)
+    const ids = result.entries.map((n) => n.id)
+    assert.ok(ids.includes('a'))
+    assert.ok(ids.includes('b'))
+    assert.ok(!ids.includes('c')) // depth 1 stops before c
+  })
+
+  it('respects maxPerLookup', () => {
+    const seeds = [{ id: 'a', linkedMemoryIds: ['b', 'c', 'd', 'e', 'f'] }]
+    const result = traverseLinkedMemoryGraph(seeds, { maxDepth: 3, maxPerLookup: 3, maxLinkedExpansion: 60 }, fetchByIds)
+    assert.strictEqual(result.entries.length, 3)
+    assert.strictEqual(result.truncated, true)
+  })
+
+  it('respects maxLinkedExpansion', () => {
+    const seeds = [{ id: 'a', linkedMemoryIds: ['b', 'c', 'd', 'e', 'f'] }]
+    const result = traverseLinkedMemoryGraph(seeds, { maxDepth: 3, maxPerLookup: 20, maxLinkedExpansion: 2 }, fetchByIds)
+    assert.strictEqual(result.expandedLinkedCount, 2)
+    assert.strictEqual(result.truncated, true)
+  })
+
+  it('handles circular links', () => {
+    const circularFetch = (ids: string[]): LinkedMemoryNode[] => {
+      const map: Record<string, string[]> = { a: ['b'], b: ['a'] }
+      return ids.map((id) => ({ id, linkedMemoryIds: map[id] || [] }))
+    }
+    const seeds = [{ id: 'a', linkedMemoryIds: ['b'] }]
+    const result = traverseLinkedMemoryGraph(seeds, { maxDepth: 10, maxPerLookup: 100, maxLinkedExpansion: 100 }, circularFetch)
+    assert.strictEqual(result.entries.length, 2) // just a and b
+    assert.strictEqual(result.truncated, false)
+  })
+})

package/src/lib/server/memory-graph.ts

@@ -0,0 +1,138 @@
+export const DEFAULT_MEMORY_REFERENCE_DEPTH = 3
+export const DEFAULT_MAX_MEMORIES_PER_LOOKUP = 20
+export const DEFAULT_MAX_LINKED_MEMORIES_EXPANDED = 60
+
+const MAX_MEMORY_REFERENCE_DEPTH = 12
+const MAX_MEMORIES_PER_LOOKUP = 200
+const MAX_LINKED_MEMORIES_EXPANDED = 1000
+
+export interface MemoryLookupLimits {
+  maxDepth: number
+  maxPerLookup: number
+  maxLinkedExpansion: number
+}
+
+export interface MemoryLookupRequest {
+  depth?: number | null
+  limit?: number | null
+  linkedLimit?: number | null
+}
+
+export interface LinkedMemoryNode {
+  id: string
+  linkedMemoryIds?: string[]
+}
+
+export interface TraversalResult<TNode extends LinkedMemoryNode> {
+  entries: TNode[]
+  truncated: boolean
+  expandedLinkedCount: number
+}
+
+function parseIntSetting(value: unknown): number | null {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number.parseInt(value, 10)
+      : Number.NaN
+  if (!Number.isFinite(parsed)) return null
+  return Math.trunc(parsed)
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value))
+}
+
+export function normalizeMemoryLookupLimits(settings: Record<string, unknown>): MemoryLookupLimits {
+  const depthRaw = parseIntSetting(settings.memoryReferenceDepth ?? settings.memoryMaxDepth)
+  const perLookupRaw = parseIntSetting(settings.maxMemoriesPerLookup ?? settings.memoryMaxPerLookup)
+  const linkedRaw = parseIntSetting(settings.maxLinkedMemoriesExpanded)
+
+  const maxDepth = clamp(depthRaw ?? DEFAULT_MEMORY_REFERENCE_DEPTH, 0, MAX_MEMORY_REFERENCE_DEPTH)
+  const maxPerLookup = clamp(perLookupRaw ?? DEFAULT_MAX_MEMORIES_PER_LOOKUP, 1, MAX_MEMORIES_PER_LOOKUP)
+  const maxLinkedExpansion = clamp(linkedRaw ?? DEFAULT_MAX_LINKED_MEMORIES_EXPANDED, 0, MAX_LINKED_MEMORIES_EXPANDED)
+
+  return { maxDepth, maxPerLookup, maxLinkedExpansion }
+}
+
+export function resolveLookupRequest(
+  defaults: MemoryLookupLimits,
+  request: MemoryLookupRequest = {},
+): MemoryLookupLimits {
+  const depth = parseIntSetting(request.depth)
+  const limit = parseIntSetting(request.limit)
+  const linkedLimit = parseIntSetting(request.linkedLimit)
+
+  return {
+    maxDepth: clamp(depth ?? defaults.maxDepth, 0, defaults.maxDepth),
+    maxPerLookup: clamp(limit ?? defaults.maxPerLookup, 1, defaults.maxPerLookup),
+    maxLinkedExpansion: clamp(linkedLimit ?? defaults.maxLinkedExpansion, 0, defaults.maxLinkedExpansion),
+  }
+}
+
+export function normalizeLinkedMemoryIds(input: unknown, selfId?: string): string[] {
+  if (!Array.isArray(input)) return []
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const raw of input) {
+    const id = typeof raw === 'string' ? raw.trim() : ''
+    if (!id || id === selfId || seen.has(id)) continue
+    seen.add(id)
+    out.push(id)
+  }
+  return out
+}
+
+export function traverseLinkedMemoryGraph<TNode extends LinkedMemoryNode>(
+  seedNodes: TNode[],
+  opts: MemoryLookupLimits,
+  fetchByIds: (ids: string[]) => TNode[],
+): TraversalResult<TNode> {
+  if (!seedNodes.length || opts.maxPerLookup <= 0) {
+    return { entries: [], truncated: false, expandedLinkedCount: 0 }
+  }
+
+  const seen = new Set<string>()
+  const seedIds = new Set(seedNodes.map((n) => n.id))
+  const out: TNode[] = []
+  let queue: TNode[] = [...seedNodes]
+  let depth = 0
+  let truncated = false
+  let expandedLinkedCount = 0
+
+  while (queue.length > 0 && depth <= opts.maxDepth) {
+    const nextQueue: TNode[] = []
+    for (const entry of queue) {
+      if (seen.has(entry.id)) continue
+
+      const isLinkedExpansion = !seedIds.has(entry.id)
+      if (isLinkedExpansion) {
+        if (expandedLinkedCount >= opts.maxLinkedExpansion) {
+          truncated = true
+          return { entries: out, truncated, expandedLinkedCount }
+        }
+        expandedLinkedCount++
+      }
+
+      seen.add(entry.id)
+      out.push(entry)
+      if (out.length >= opts.maxPerLookup) {
+        truncated = true
+        return { entries: out, truncated, expandedLinkedCount }
+      }
+
+      if (depth >= opts.maxDepth) continue
+      const linkedIds = normalizeLinkedMemoryIds(entry.linkedMemoryIds, entry.id).filter((id) => !seen.has(id))
+      if (!linkedIds.length) continue
+      const linkedEntries = fetchByIds(linkedIds)
+      for (const linked of linkedEntries) {
+        if (!linked?.id || seen.has(linked.id)) continue
+        nextQueue.push(linked)
+      }
+    }
+    queue = nextQueue
+    depth++
+  }
+
+  return { entries: out, truncated, expandedLinkedCount }
+}

package/src/lib/server/openclaw-health.ts

@@ -0,0 +1,245 @@
+import { deriveOpenClawWsUrl, normalizeOpenClawEndpoint } from '@/lib/openclaw-endpoint'
+import { decryptKey, loadCredentials } from './storage'
+
+export interface OpenClawHealthInput {
+  endpoint?: string | null
+  credentialId?: string | null
+  token?: string | null
+  model?: string | null
+  timeoutMs?: number
+}
+
+export interface OpenClawHealthResult {
+  ok: boolean
+  endpoint: string
+  wsUrl: string
+  authProvided: boolean
+  model: string | null
+  models: string[]
+  modelsStatus: number | null
+  chatStatus: number | null
+  completionSample?: string
+  error?: string
+  hint?: string
+}
+
+function normalizeToken(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function resolveCredentialToken(credentialId?: string | null): string | null {
+  const id = normalizeToken(credentialId)
+  if (!id) return null
+  const credentials = loadCredentials()
+  const credential = credentials[id]
+  if (!credential?.encryptedKey) return null
+  try {
+    return decryptKey(credential.encryptedKey)
+  } catch {
+    return null
+  }
+}
+
+function extractModels(payload: any): string[] {
+  const models = Array.isArray(payload?.data) ? payload.data : []
+  return models
+    .map((item: any) => (typeof item?.id === 'string' ? item.id.trim() : ''))
+    .filter(Boolean)
+}
+
+function extractChatText(payload: any): string {
+  const content = payload?.choices?.[0]?.message?.content
+  if (typeof content === 'string') return content.trim()
+  if (Array.isArray(content)) {
+    return content
+      .map((block: any) => {
+        if (typeof block?.text === 'string') return block.text
+        if (typeof block?.content === 'string') return block.content
+        return ''
+      })
+      .join(' ')
+      .trim()
+  }
+  return ''
+}
+
+function describeHttpError(status: number): { error: string; hint?: string } {
+  if (status === 401) {
+    return {
+      error: 'OpenClaw endpoint rejected auth (401 Unauthorized).',
+      hint: 'Set a valid OpenClaw token credential on the agent/session or pass credentialId/token to this health check.',
+    }
+  }
+  if (status === 404) {
+    return {
+      error: 'OpenClaw endpoint path is invalid (404).',
+      hint: 'Point to the gateway root/ws URL and let SwarmClaw normalize it, or use an explicit /v1 endpoint.',
+    }
+  }
+  if (status === 405) {
+    return {
+      error: 'OpenClaw endpoint method mismatch (405).',
+      hint: 'Ensure this is an OpenAI-compatible chat endpoint exposed by the OpenClaw gateway.',
+    }
+  }
+  return {
+    error: `OpenClaw endpoint returned HTTP ${status}.`,
+  }
+}
+
+function createTimeoutError(message: string): Error {
+  const timeoutErr = new Error(message)
+  ;(timeoutErr as any).name = 'TimeoutError'
+  return timeoutErr
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onTimeout?: () => void, message?: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  try {
+    return await new Promise<T>((resolve, reject) => {
+      timer = setTimeout(() => {
+        try { onTimeout?.() } catch { /* noop */ }
+        reject(createTimeoutError(message || `Request timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      promise
+        .then((value) => {
+          if (timer) clearTimeout(timer)
+          resolve(value)
+        })
+        .catch((err) => {
+          if (timer) clearTimeout(timer)
+          reject(err)
+        })
+    })
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+async function fetchJsonWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<{ response: Response; body: any }> {
+  const controller = new AbortController()
+  try {
+    const response = await withTimeout(
+      fetch(url, { ...init, signal: controller.signal }),
+      timeoutMs,
+      () => controller.abort(),
+      `Request timed out after ${timeoutMs}ms`,
+    )
+    const text = await withTimeout(
+      response.text(),
+      timeoutMs,
+      () => controller.abort(),
+      `Response read timed out after ${timeoutMs}ms`,
+    )
+    let body: any = {}
+    if (text) {
+      try {
+        body = JSON.parse(text)
+      } catch {
+        body = {}
+      }
+    }
+    return { response, body }
+  } catch (err: any) {
+    if (err?.name === 'AbortError') throw createTimeoutError(`Request timed out after ${timeoutMs}ms`)
+    throw err
+  }
+}
+
+export async function probeOpenClawHealth(input: OpenClawHealthInput): Promise<OpenClawHealthResult> {
+  const endpoint = normalizeOpenClawEndpoint(input.endpoint || undefined)
+  const wsUrl = deriveOpenClawWsUrl(endpoint)
+  const timeoutMs = Math.max(1000, Math.min(30_000, Math.trunc(input.timeoutMs || 8000)))
+  const token = normalizeToken(input.token) || resolveCredentialToken(input.credentialId)
+  const authProvided = !!token
+  const headers: Record<string, string> = {
+    // Use text/plain to bypass Express body parsers in Hostinger/proxy setups.
+    // The OpenClaw gateway parses the body as JSON regardless of Content-Type.
+    'content-type': 'text/plain',
+  }
+  if (token) headers.authorization = `Bearer ${token}`
+
+  let models: string[] = []
+  let modelsStatus: number | null = null
+  let chatStatus: number | null = null
+  let completionSample = ''
+  let lastError = ''
+  let lastHint: string | undefined
+
+  try {
+    const { response: modelsRes, body } = await fetchJsonWithTimeout(`${endpoint}/models`, {
+      headers,
+      cache: 'no-store',
+    }, timeoutMs)
+    modelsStatus = modelsRes.status
+    if (modelsRes.ok) {
+      models = extractModels(body)
+    } else {
+      const err = describeHttpError(modelsRes.status)
+      lastError = err.error
+      lastHint = err.hint
+    }
+  } catch (err: any) {
+    if (err?.name === 'TimeoutError') {
+      lastError = `OpenClaw models probe timed out after ${timeoutMs}ms.`
+    } else {
+      lastError = err?.message || 'Failed to connect to OpenClaw endpoint.'
+    }
+    return {
+      ok: false,
+      endpoint,
+      wsUrl,
+      authProvided,
+      model: null,
+      models: [],
+      modelsStatus: null,
+      chatStatus: null,
+      error: lastError,
+      hint: 'Verify the OpenClaw gateway is running and reachable at this host/port.',
+    }
+  }
+
+  const model = normalizeToken(input.model) || models[0] || 'default'
+
+  try {
+    const { response: chatRes, body } = await fetchJsonWithTimeout(`${endpoint}/chat/completions`, {
+      method: 'POST',
+      headers,
+      cache: 'no-store',
+      body: JSON.stringify({
+        model,
+        messages: [{ role: 'user', content: 'Reply with OPENCLAW_HEALTH_OK' }],
+        stream: false,
+        max_tokens: 12,
+      }),
+    }, timeoutMs)
+    chatStatus = chatRes.status
+    if (!chatRes.ok) {
+      const err = describeHttpError(chatRes.status)
+      lastError = err.error
+      lastHint = err.hint || lastHint
+    } else {
+      completionSample = extractChatText(body).slice(0, 240)
+    }
+  } catch (err: any) {
+    if (err?.name === 'TimeoutError') {
+      lastError = `OpenClaw chat probe timed out after ${timeoutMs}ms.`
+    } else {
+      lastError = err?.message || 'OpenClaw chat probe failed.'
+    }
+  }
+
+  return {
+    ok: !!chatStatus && chatStatus >= 200 && chatStatus < 300,
+    endpoint,
+    wsUrl,
+    authProvided,
+    model,
+    models,
+    modelsStatus,
+    chatStatus,
+    completionSample: completionSample || undefined,
+    error: lastError || undefined,
+    hint: lastHint,
+  }
+}