@swarmclawai/swarmclaw 0.7.1 → 0.7.3

package/src/lib/server/structured-extract.test.ts

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+import { PROVIDERS } from '../providers'
+import { runStructuredExtraction } from './structured-extract'
+
+const originalOllamaHandler = PROVIDERS.ollama.handler.streamChat
+
+afterEach(() => {
+  PROVIDERS.ollama.handler.streamChat = originalOllamaHandler
+})
+
+describe('runStructuredExtraction', () => {
+  it('parses fenced JSON output from the current provider', async () => {
+    PROVIDERS.ollama.handler.streamChat = async () => '```json\n{"name":"Ada","score":10}\n```'
+
+    const result = await runStructuredExtraction({
+      session: {
+        id: 'session-1',
+        provider: 'ollama',
+        model: 'qwen3.5',
+        credentialId: null,
+        fallbackCredentialIds: [],
+        apiEndpoint: 'http://localhost:11434',
+      },
+      text: 'Ada scored 10.',
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          score: { type: 'number' },
+        },
+        required: ['name', 'score'],
+      },
+      instruction: 'Extract the person and score.',
+    })
+
+    assert.deepEqual(result.object, { name: 'Ada', score: 10 })
+    assert.deepEqual(result.validationErrors, [])
+  })
+
+  it('repairs invalid JSON with a second pass', async () => {
+    let callCount = 0
+    PROVIDERS.ollama.handler.streamChat = async () => {
+      callCount += 1
+      return callCount === 1 ? 'name: Ada' : '{"name":"Ada"}'
+    }
+
+    const result = await runStructuredExtraction({
+      session: {
+        id: 'session-2',
+        provider: 'ollama',
+        model: 'qwen3.5',
+        credentialId: null,
+        fallbackCredentialIds: [],
+        apiEndpoint: 'http://localhost:11434',
+      },
+      text: 'Ada',
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+        },
+        required: ['name'],
+      },
+      instruction: 'Extract the name.',
+    })
+
+    assert.equal(callCount, 2)
+    assert.deepEqual(result.object, { name: 'Ada' })
+    assert.deepEqual(result.validationErrors, [])
+  })
+})

package/src/lib/server/structured-extract.ts

@@ -0,0 +1,373 @@
+import type { Session } from '@/types'
+import { getProvider, streamChatWithFailover } from '@/lib/providers'
+import { decryptKey, loadCredentials } from './storage'
+import { extractDocumentArtifact, type DocumentArtifact } from './document-utils'
+
+type JsonSchemaLike = Record<string, unknown>
+
+interface ExtractionSession extends Pick<Session, 'id' | 'provider' | 'model' | 'credentialId' | 'fallbackCredentialIds' | 'apiEndpoint' | 'thinkingLevel'> {
+  name?: string
+  cwd?: string
+}
+
+export interface StructuredExtractionSource {
+  kind: 'text' | 'file' | 'mixed'
+  text: string
+  filePath?: string | null
+  artifact?: DocumentArtifact | null
+}
+
+export interface StructuredExtractionResult {
+  object: unknown
+  raw: string
+  validationErrors: string[]
+  provider: string
+  model: string
+  source: StructuredExtractionSource
+}
+
+function resolveApiKey(session: ExtractionSession): string | null {
+  const provider = getProvider(session.provider)
+  if (!provider) throw new Error(`Unknown provider: ${session.provider}`)
+  if (provider.requiresApiKey) {
+    if (!session.credentialId) throw new Error('No API key configured for this session')
+    const creds = loadCredentials()
+    const cred = creds[session.credentialId]
+    if (!cred?.encryptedKey) throw new Error('API key not found. Please add one in Settings.')
+    return decryptKey(cred.encryptedKey)
+  }
+  if (provider.optionalApiKey && session.credentialId) {
+    const creds = loadCredentials()
+    const cred = creds[session.credentialId]
+    if (cred?.encryptedKey) {
+      try {
+        return decryptKey(cred.encryptedKey)
+      } catch {
+        return null
+      }
+    }
+  }
+  return null
+}
+
+function normalizeSchemaInput(schema: unknown): JsonSchemaLike {
+  if (schema && typeof schema === 'object' && !Array.isArray(schema)) return schema as JsonSchemaLike
+  if (typeof schema === 'string' && schema.trim()) {
+    const parsed = JSON.parse(schema)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as JsonSchemaLike
+  }
+  throw new Error('schema must be a JSON object or a JSON string representing an object.')
+}
+
+function defaultSummarySchema(): JsonSchemaLike {
+  return {
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      keyPoints: { type: 'array', items: { type: 'string' } },
+      entities: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            type: { type: 'string' },
+            value: {},
+          },
+          required: ['name'],
+        },
+      },
+    },
+    required: ['summary', 'keyPoints'],
+  }
+}
+
+function normalizeText(value: string, maxChars = 120_000): string {
+  const cleaned = value.replace(/\r\n/g, '\n').replace(/\u0000/g, '').trim()
+  if (cleaned.length <= maxChars) return cleaned
+  return `${cleaned.slice(0, maxChars)}\n\n[... truncated ...]`
+}
+
+function extractJsonBlock(text: string): string | null {
+  const raw = (text || '').trim()
+  if (!raw) return null
+
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim()
+  if (fenced) return fenced
+
+  if ((raw.startsWith('{') && raw.endsWith('}')) || (raw.startsWith('[') && raw.endsWith(']'))) {
+    return raw
+  }
+
+  let inString = false
+  let escaped = false
+  let start = -1
+  const stack: string[] = []
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index]
+    if (inString) {
+      if (escaped) {
+        escaped = false
+        continue
+      }
+      if (char === '\\') {
+        escaped = true
+        continue
+      }
+      if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      continue
+    }
+    if (char === '{' || char === '[') {
+      if (stack.length === 0) start = index
+      stack.push(char)
+      continue
+    }
+    if (char === '}' || char === ']') {
+      const last = stack.at(-1)
+      if ((char === '}' && last === '{') || (char === ']' && last === '[')) {
+        stack.pop()
+        if (stack.length === 0 && start >= 0) {
+          return raw.slice(start, index + 1)
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+function parseModelJson(text: string): unknown {
+  const candidate = extractJsonBlock(text)
+  if (!candidate) throw new Error('Model did not return JSON.')
+  return JSON.parse(candidate)
+}
+
+function typeMatches(value: unknown, expected: string): boolean {
+  if (expected === 'array') return Array.isArray(value)
+  if (expected === 'object') return !!value && typeof value === 'object' && !Array.isArray(value)
+  if (expected === 'string') return typeof value === 'string'
+  if (expected === 'number') return typeof value === 'number' && Number.isFinite(value)
+  if (expected === 'integer') return typeof value === 'number' && Number.isInteger(value)
+  if (expected === 'boolean') return typeof value === 'boolean'
+  if (expected === 'null') return value === null
+  return true
+}
+
+function validateJsonLikeSchema(
+  value: unknown,
+  schema: JsonSchemaLike,
+  path = '$',
+  errors: string[] = [],
+): string[] {
+  const expected = schema.type
+  if (typeof expected === 'string' && !typeMatches(value, expected)) {
+    errors.push(`${path} should be ${expected}`)
+    return errors
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.some((entry) => JSON.stringify(entry) === JSON.stringify(value))) {
+    errors.push(`${path} must be one of the allowed enum values`)
+  }
+
+  if (expected === 'object' && value && typeof value === 'object' && !Array.isArray(value)) {
+    const asRecord = value as Record<string, unknown>
+    const properties = (schema.properties && typeof schema.properties === 'object' && !Array.isArray(schema.properties))
+      ? schema.properties as Record<string, JsonSchemaLike>
+      : {}
+    const required = Array.isArray(schema.required) ? schema.required.filter((entry): entry is string => typeof entry === 'string') : []
+    for (const key of required) {
+      if (!(key in asRecord)) errors.push(`${path}.${key} is required`)
+    }
+    for (const [key, childSchema] of Object.entries(properties)) {
+      if (!(key in asRecord)) continue
+      validateJsonLikeSchema(asRecord[key], childSchema, `${path}.${key}`, errors)
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(asRecord)) {
+        if (!(key in properties)) errors.push(`${path}.${key} is not allowed`)
+      }
+    }
+  }
+
+  if (expected === 'array' && Array.isArray(value)) {
+    const itemSchema = (schema.items && typeof schema.items === 'object' && !Array.isArray(schema.items))
+      ? schema.items as JsonSchemaLike
+      : null
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+      errors.push(`${path} must contain at least ${schema.minItems} items`)
+    }
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+      errors.push(`${path} must contain at most ${schema.maxItems} items`)
+    }
+    if (itemSchema) {
+      value.slice(0, 100).forEach((entry, index) => validateJsonLikeSchema(entry, itemSchema, `${path}[${index}]`, errors))
+    }
+  }
+
+  return errors
+}
+
+async function callExtractionModel(params: {
+  session: ExtractionSession
+  prompt: string
+}): Promise<string> {
+  const provider = getProvider(params.session.provider)
+  if (!provider) throw new Error(`Unknown provider: ${params.session.provider}`)
+
+  const apiKey = resolveApiKey(params.session)
+  const streamedText: string[] = []
+  const streamedErrors: string[] = []
+
+  const raw = await streamChatWithFailover({
+    session: {
+      id: `${params.session.id}:extract:${Date.now()}`,
+      provider: params.session.provider,
+      model: params.session.model,
+      credentialId: params.session.credentialId ?? null,
+      fallbackCredentialIds: params.session.fallbackCredentialIds || [],
+      apiEndpoint: params.session.apiEndpoint || undefined,
+      thinkingLevel: params.session.thinkingLevel,
+    },
+    message: params.prompt,
+    apiKey,
+    active: new Map(),
+    loadHistory: () => [],
+    write: (chunk) => {
+      for (const line of chunk.split('\n')) {
+        if (!line.startsWith('data: ')) continue
+        try {
+          const event = JSON.parse(line.slice(6).trim()) as Record<string, unknown>
+          if (event.t === 'd' && typeof event.text === 'string') streamedText.push(event.text)
+          if (event.t === 'err' && typeof event.text === 'string') streamedErrors.push(event.text)
+        } catch {
+          // ignore malformed SSE fragments
+        }
+      }
+    },
+  })
+
+  const text = (raw || streamedText.join('')).trim()
+  if (!text) {
+    throw new Error(streamedErrors[0] || `Provider "${provider.name}" returned no content.`)
+  }
+  return text
+}
+
+function buildExtractionPrompt(params: {
+  instruction?: string | null
+  schema: JsonSchemaLike
+  source: StructuredExtractionSource
+}): string {
+  const parts = [
+    'Extract structured data from the provided source.',
+    'Return only valid JSON. Do not include markdown fences, commentary, or explanatory text.',
+    'If a field cannot be determined, use null, an empty string, or an empty array based on the schema.',
+  ]
+  if (params.instruction?.trim()) {
+    parts.push(`Task:\n${params.instruction.trim()}`)
+  }
+  parts.push(`JSON Schema:\n${JSON.stringify(params.schema, null, 2)}`)
+  if (params.source.artifact) {
+    const artifact = params.source.artifact
+    parts.push(`Source metadata:\n${JSON.stringify({
+      filePath: artifact.filePath,
+      fileName: artifact.fileName,
+      ext: artifact.ext,
+      method: artifact.method,
+      metadata: artifact.metadata,
+      tableCount: artifact.tables.length,
+    }, null, 2)}`)
+  }
+  parts.push(`Source text:\n${params.source.text}`)
+  return parts.join('\n\n')
+}
+
+async function prepareSource(params: {
+  text?: string | null
+  filePath?: string | null
+  preferOcr?: boolean
+  maxChars?: number
+}): Promise<StructuredExtractionSource> {
+  const chunks: string[] = []
+  let artifact: DocumentArtifact | null = null
+
+  if (params.filePath) {
+    artifact = await extractDocumentArtifact(params.filePath, {
+      preferOcr: params.preferOcr,
+      maxChars: params.maxChars,
+    })
+    if (artifact.text.trim()) chunks.push(artifact.text)
+  }
+
+  if (params.text?.trim()) chunks.push(params.text.trim())
+  if (chunks.length === 0) throw new Error('text or filePath is required.')
+
+  return {
+    kind: params.filePath && params.text ? 'mixed' : params.filePath ? 'file' : 'text',
+    filePath: params.filePath || null,
+    artifact,
+    text: normalizeText(chunks.join('\n\n'), params.maxChars || 120_000),
+  }
+}
+
+export async function runStructuredExtraction(params: {
+  session: ExtractionSession
+  text?: string | null
+  filePath?: string | null
+  instruction?: string | null
+  schema?: unknown
+  preferOcr?: boolean
+  maxChars?: number
+}): Promise<StructuredExtractionResult> {
+  if (!params.session.provider || !params.session.model) {
+    throw new Error('Current session is missing provider/model configuration.')
+  }
+
+  const source = await prepareSource({
+    text: params.text,
+    filePath: params.filePath,
+    preferOcr: params.preferOcr,
+    maxChars: params.maxChars,
+  })
+  const schema = params.schema === undefined ? defaultSummarySchema() : normalizeSchemaInput(params.schema)
+  const prompt = buildExtractionPrompt({
+    instruction: params.instruction,
+    schema,
+    source,
+  })
+
+  let raw = await callExtractionModel({
+    session: params.session,
+    prompt,
+  })
+
+  let parsed: unknown
+  try {
+    parsed = parseModelJson(raw)
+  } catch (error) {
+    raw = await callExtractionModel({
+      session: params.session,
+      prompt: [
+        'Repair the invalid JSON below so it becomes valid JSON that matches the provided schema.',
+        'Return only JSON.',
+        `JSON Schema:\n${JSON.stringify(schema, null, 2)}`,
+        `Invalid output:\n${raw}`,
+      ].join('\n\n'),
+    })
+    parsed = parseModelJson(raw)
+  }
+
+  const validationErrors = validateJsonLikeSchema(parsed, schema).slice(0, 50)
+  return {
+    object: parsed,
+    raw,
+    validationErrors,
+    provider: params.session.provider,
+    model: params.session.model,
+    source,
+  }
+}

package/src/lib/server/task-mention.test.ts

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 import type { Agent } from '@/types'
-import { parseMentionedAgentId, resolveTaskAgentFromDescription } from './task-mention'
+import { parseAssignedAgentId, parseMentionedAgentId, resolveAgentReference, resolveTaskAgentFromDescription } from './task-mention'
 
 const now = Date.now()
 const agents: Record<string, Agent> = {
@@ -37,5 +37,19 @@ describe('task-mention', () => {
     const resolved = resolveTaskAgentFromDescription('No mention here', 'default', agents)
     assert.equal(resolved, 'default')
   })
-})
 
+  it('resolves agent ids directly', () => {
+    const resolved = resolveAgentReference('coder', agents)
+    assert.equal(resolved, 'coder')
+  })
+
+  it('parses plain-language assignment phrases', () => {
+    const assigned = parseAssignedAgentId('Create this task and assign it to agent "default".', agents)
+    assert.equal(assigned, 'default')
+  })
+
+  it('resolves task assignment without @mentions', () => {
+    const resolved = resolveTaskAgentFromDescription('Please delegate this to CodeBot.', 'default', agents)
+    assert.equal(resolved, 'coder')
+  })
+})

package/src/lib/server/task-mention.ts

@@ -1,5 +1,39 @@
 import type { Agent } from '@/types'
 
+function normalizeReference(reference: string): string {
+  return reference
+    .trim()
+    .replace(/^@/, '')
+    .replace(/^agent\s+/i, '')
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .replace(/[.,!?;:]+$/g, '')
+    .trim()
+    .toLowerCase()
+}
+
+export function resolveAgentReference(
+  reference: string,
+  agents: Record<string, Agent>,
+): string | null {
+  const normalized = normalizeReference(reference)
+  if (!normalized) return null
+
+  const agentList = Object.values(agents)
+  const exactId = agentList.find((agent) => agent.id.toLowerCase() === normalized)
+  if (exactId) return exactId.id
+
+  const exactName = agentList.find((agent) => agent.name.toLowerCase() === normalized)
+  if (exactName) return exactName.id
+
+  const startsWithId = agentList.find((agent) => agent.id.toLowerCase().startsWith(normalized))
+  if (startsWithId) return startsWithId.id
+
+  const startsWithName = agentList.find((agent) => agent.name.toLowerCase().startsWith(normalized))
+  if (startsWithName) return startsWithName.id
+
+  return null
+}
+
 /**
  * Parse @AgentName mentions from text and resolve to an agent ID.
  * Uses case-insensitive exact match, then falls back to starts-with.
@@ -13,16 +47,31 @@ export function parseMentionedAgentId(
   let match: RegExpExecArray | null
 
   while ((match = mentionRegex.exec(description)) !== null) {
-    const mention = (match[1] || '').toLowerCase().replace(/[.,!?;:]+$/g, '')
-    if (!mention) continue
+    const mention = match[1] || ''
+    const resolved = resolveAgentReference(mention, agents)
+    if (resolved) return resolved
+  }
+
+  return null
+}
 
-    // Exact name match (case-insensitive)
-    const exact = agentList.find((a) => a.name.toLowerCase() === mention)
-    if (exact) return exact.id
+export function parseAssignedAgentId(
+  description: string,
+  agents: Record<string, Agent>,
+): string | null {
+  const patterns = [
+    /(?:assign(?:ed)?|delegate(?:d)?|route(?:d)?|hand(?:ed)?)(?:\s+\w+){0,4}\s+to\s+(?:agent\s+)?["'`]?([^"'`\n]+?)["'`]?(?=$|[\s.,;:])/gi,
+    /(?:assignee|assigned[_\s-]?to|agent(?:\s+id)?)\s*[:=]\s*["'`]?([^"'`\n]+?)["'`]?(?=$|[\s.,;:])/gi,
+    /for\s+agent\s+["'`]?([^"'`\n]+?)["'`]?(?=$|[\s.,;:])/gi,
+  ]
 
-    // Starts-with match (for partial names like @code matching "CodeBot")
-    const startsWith = agentList.find((a) => a.name.toLowerCase().startsWith(mention))
-    if (startsWith) return startsWith.id
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(description)) !== null) {
+      const candidate = (match[1] || '').trim()
+      const resolved = resolveAgentReference(candidate, agents)
+      if (resolved) return resolved
+    }
   }
 
   return null
@@ -30,7 +79,7 @@ export function parseMentionedAgentId(
 
 /**
  * Resolve task agent: if description has an @mention, use that agent.
- * Otherwise fall back to currentAgentId.
+ * Otherwise fall back to an explicit assignment phrase, then currentAgentId.
  */
 export function resolveTaskAgentFromDescription(
   description: string,
@@ -38,5 +87,7 @@ export function resolveTaskAgentFromDescription(
   agents: Record<string, Agent>,
 ): string {
   const mentioned = parseMentionedAgentId(description, agents)
-  return mentioned || currentAgentId
+  if (mentioned) return mentioned
+  const assigned = parseAssignedAgentId(description, agents)
+  return assigned || currentAgentId
 }