@lota-sdk/core 0.1.24 → 0.1.26

package/src/runtime/social-chat.ts

@@ -4,27 +4,19 @@ import {
   buildSlackSocialReplyMarkdown,
   CONSULT_SPECIALIST_TOOL_NAME,
   ConsultSpecialistArgsSchema,
-  stripSlackToolExecutionNoticeMarkdown,
 } from '@lota-sdk/shared'
 import type { ChatMessage, ConsultSpecialistArgs } from '@lota-sdk/shared'
-import { stepCountIs, tool as createTool } from 'ai'
-import type { ToolLoopAgent, ToolSet } from 'ai'
+import { tool as createTool } from 'ai'
 import { Chat, ConsoleLogger } from 'chat'
 import type { Message, Thread, WebhookOptions } from 'chat'
 import type IORedis from 'ioredis'
 
-import {
-  agentDisplayNames,
-  createAgent,
-  getAgentRuntimeConfig,
-  teamConsultParticipants,
-} from '../config/agent-defaults'
+import { agentDisplayNames, teamConsultParticipants } from '../config/agent-defaults'
 import { aiLogger } from '../config/logger'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
+import { enqueueRegularChatMemoryDigest, enqueueSkillExtraction } from '../queues/organization-learning.queue'
 import { enqueuePostChatMemory } from '../queues/post-chat-memory.queue'
-import { enqueueRegularChatMemoryDigest } from '../queues/regular-chat-memory-digest.queue'
-import { enqueueSkillExtraction } from '../queues/skill-extraction.queue'
 import type {
   BuildSocialChatAgentToolsParams,
   LotaRuntimeSocialChatConfig,
@@ -37,7 +29,26 @@ import { socialChatHistoryService } from '../services/social-chat-history.servic
 import { safeEnqueue } from '../utils/async'
 import { buildAgentPromptContext } from './agent-prompt-context'
 import { createServerRunAbortController } from './agent-stream-helpers'
-import { buildAgentHistoryMessages, extractMessageText, toHistoryMessages } from './workstream-chat-helpers'
+import { runSocialAgentTurn, withLoggedSocialToolSet } from './social-chat-agent-runner'
+import {
+  collectThreadMessages,
+  createSocialChatCursorId,
+  normalizeSocialHistoryMessage,
+  readSlackAuthorName,
+  buildSocialChatThreadTranscript,
+} from './social-chat-history'
+import {
+  buildLeadSocialChatPrompt,
+  buildSocialChatIdentitySection,
+  buildSpecialistSocialChatPrompt,
+} from './social-chat-prompts'
+import { runSpecialistSession } from './specialist-runner'
+import {
+  buildAgentHistoryMessages,
+  extractMessageText,
+  toHistoryMessages,
+  toOptionalTrimmedString,
+} from './workstream-chat-helpers'
 
 const DEFAULT_SOCIAL_CHAT_AGENT_ID = 'socialChat'
 const DEFAULT_SOCIAL_CHAT_AGENT_DISPLAY_NAME = 'Lota'
@@ -45,8 +56,6 @@ const DEFAULT_SOCIAL_CHAT_STATE_PREFIX = 'lota:social:chat-sdk'
 const DEFAULT_SOCIAL_CHAT_DEDUPE_TTL_MS = 15 * 60 * 1000
 const PRESEEDED_MEMORY_LOOKUP_LIMIT = 3
 
-type SocialChatAgent = ToolLoopAgent<never, ToolSet>
-
 export interface LotaRuntimeSocialChat {
   enabled: boolean
   initialize(): Promise<void>
@@ -76,96 +85,6 @@ function createDisabledSocialChatRuntime(): LotaRuntimeSocialChat {
   }
 }
 
-function toOptionalTrimmedString(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined
-  const normalized = value.trim()
-  return normalized.length > 0 ? normalized : undefined
-}
-
-function readSlackAuthorName(message: Message): string | undefined {
-  return (
-    toOptionalTrimmedString(message.author.fullName) ??
-    toOptionalTrimmedString(message.author.userName) ??
-    toOptionalTrimmedString(message.author.userId)
-  )
-}
-
-function buildSocialChatIdentitySection(agentDisplayName: string): string {
-  return [
-    '<social-chat-agent>',
-    `You are ${agentDisplayName}, the social chat agent for this workspace.`,
-    '- You respond inside Slack threads.',
-    '- Use the available tools, memories, learned skills, and workspace knowledge before guessing.',
-    '- If the answer may depend on prior workspace decisions, preferences, promises, history, or relationship context, check memory with the available memory tools before answering.',
-    '- If the user shares a URL or asks about a website/page, read it with fetchWebpage before answering. Do not summarize website contents from prior knowledge.',
-    '- When another roster agent is better suited for a question, consult that specialist and then synthesize the final answer yourself.',
-    '- Keep the final reply crisp and readable for Slack unless the user explicitly asks for depth.',
-    '</social-chat-agent>',
-  ].join('\n')
-}
-
-function buildThreadTranscript(
-  messages: Array<{
-    role: 'user' | 'assistant'
-    parts: Array<Record<string, unknown>>
-    metadata?: Record<string, unknown>
-  }>,
-): string {
-  const historyMessages = toHistoryMessages(messages)
-  if (historyMessages.length === 0) return 'No prior thread history.'
-
-  return historyMessages
-    .map((message) =>
-      message.role === 'user' ? `User: ${message.content}` : `${message.agentName ?? 'Assistant'}: ${message.content}`,
-    )
-    .join('\n\n')
-}
-
-function buildLeadAgentPrompt(params: {
-  agentDisplayName: string
-  channelId: string
-  threadId: string
-  transcript: string
-  latestUserMessage: string
-  latestAuthorName?: string
-}): string {
-  return [
-    `Platform: Slack`,
-    `Channel ID: ${params.channelId}`,
-    `Thread ID: ${params.threadId}`,
-    `Current Slack author: ${params.latestAuthorName ?? 'Unknown'}`,
-    '',
-    `You are replying as ${params.agentDisplayName}.`,
-    '',
-    '<thread-transcript>',
-    params.transcript,
-    '</thread-transcript>',
-    '',
-    'Latest user message:',
-    params.latestUserMessage,
-  ].join('\n')
-}
-
-function buildSpecialistPrompt(params: {
-  requesterName: string
-  agentName: string
-  task: string
-  transcript: string
-}): string {
-  return [
-    `${params.requesterName} needs specialist help from ${params.agentName}.`,
-    '',
-    '<thread-transcript>',
-    params.transcript,
-    '</thread-transcript>',
-    '',
-    'Specialist task:',
-    params.task,
-    '',
-    'Answer only with the specialist guidance that should be used in the final Slack reply.',
-  ].join('\n')
-}
-
 function createAssistantMessage(params: { agentId: string; agentName: string; text: string }): ChatMessage {
   return {
     id: Bun.randomUUIDv7(),
@@ -175,10 +94,6 @@ function createAssistantMessage(params: { agentId: string; agentName: string; te
   }
 }
 
-function createCursorId(message: { workspaceId: string; threadId: string; messageId: string }): string {
-  return `social:slack:${message.workspaceId}:${message.threadId}:${message.messageId}`
-}
-
 function toSafeJobIdSegment(value: string): string {
   return value.replace(/[^a-zA-Z0-9_-]/g, '_')
 }
@@ -192,132 +107,6 @@ function createSocialMemoryDedupeKey(params: { workspaceId: string; threadId: st
   ].join('-')
 }
 
-interface ExecutableToolDefinition {
-  execute: (...args: unknown[]) => Promise<unknown>
-}
-
-function withLoggedToolSet(
-  tools: ToolSet,
-  params: { agentId: string; channelId: string; threadId: string; executedToolNames: string[] },
-): ToolSet {
-  return Object.fromEntries(
-    Object.entries(tools).map(([toolName, toolDefinition]) => {
-      if (
-        typeof toolDefinition !== 'object' ||
-        !('execute' in toolDefinition) ||
-        typeof toolDefinition.execute !== 'function'
-      ) {
-        return [toolName, toolDefinition]
-      }
-
-      const executableTool = toolDefinition as typeof toolDefinition & ExecutableToolDefinition
-
-      return [
-        toolName,
-        {
-          ...toolDefinition,
-          execute: async (...args: unknown[]): Promise<unknown> => {
-            aiLogger.info`Slack social-chat tool start: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
-            try {
-              const result: unknown = await executableTool.execute(...args)
-              params.executedToolNames.push(toolName)
-              aiLogger.info`Slack social-chat tool finish: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}`
-              return result
-            } catch (error) {
-              aiLogger.warn`Slack social-chat tool failed: agentId=${params.agentId}, tool=${toolName}, channelId=${params.channelId}, threadId=${params.threadId}, error=${error}`
-              throw error
-            }
-          },
-        },
-      ]
-    }),
-  )
-}
-
-function normalizeSocialHistoryMessage(params: {
-  workspaceId: string
-  channelId: string
-  agentId: string
-  agentDisplayName: string
-  message: Message
-  textOverride?: string
-}): {
-  source: 'social'
-  sourceId: string
-  platform: 'slack'
-  workspaceId: string
-  channelId: string
-  threadId: string
-  messageId: string
-  role: 'user' | 'assistant'
-  parts: Array<Record<string, unknown>>
-  metadata?: Record<string, unknown>
-  cursor: { createdAt: Date; id: string }
-} | null {
-  const role: 'user' | 'assistant' = params.message.author.isMe ? 'assistant' : 'user'
-  const text = toOptionalTrimmedString(
-    role === 'assistant'
-      ? stripSlackToolExecutionNoticeMarkdown(params.textOverride ?? params.message.text)
-      : (params.textOverride ?? params.message.text),
-  )
-  const fileParts = params.message.attachments.map((attachment) => ({
-    type: 'file',
-    filename: attachment.name ?? 'attachment',
-    mediaType: attachment.mimeType ?? 'application/octet-stream',
-    sizeBytes: typeof attachment.size === 'number' ? attachment.size : null,
-    storageKey: attachment.url ?? 'external',
-  }))
-  const parts = [...(text ? [{ type: 'text', text }] : []), ...fileParts]
-  if (parts.length === 0) return null
-
-  const createdAt = params.message.metadata.dateSent
-  const metadata: Record<string, unknown> = {
-    platform: 'slack',
-    channelId: params.channelId,
-    threadId: params.message.threadId,
-    messageId: params.message.id,
-    authorId: params.message.author.userId,
-    authorName: readSlackAuthorName(params.message),
-  }
-  if (role === 'assistant') {
-    metadata.agentId = params.agentId
-    metadata.agentName = params.agentDisplayName
-  }
-
-  return {
-    source: 'social',
-    sourceId: `slack:${params.channelId}:${params.message.threadId}`,
-    platform: 'slack',
-    workspaceId: params.workspaceId,
-    channelId: params.channelId,
-    threadId: params.message.threadId,
-    messageId: params.message.id,
-    role,
-    parts,
-    metadata,
-    cursor: {
-      createdAt,
-      id: createCursorId({
-        workspaceId: params.workspaceId,
-        threadId: params.message.threadId,
-        messageId: params.message.id,
-      }),
-    },
-  }
-}
-
-async function collectThreadMessages(thread: Thread, incomingMessage: Message): Promise<Message[]> {
-  try {
-    const messages: Message[] = []
-    for await (const message of thread.allMessages) {
-      messages.push(message)
-    }
-    return messages.length > 0 ? messages : [incomingMessage]
-  } catch {
-    return thread.recentMessages.length > 0 ? [...thread.recentMessages] : [incomingMessage]
-  }
-}
-
 function buildBuildToolsParams(params: {
   agentId: string
   context: LotaSocialChatResolvedContext
@@ -395,7 +184,7 @@ export function createSocialChatRuntime(params: {
       threadId: thread.id,
       messageId: incomingMessage.id,
       text: incomingMessage.text.trim(),
-      authorId: toOptionalTrimmedString(incomingMessage.author.userId),
+      authorId: toOptionalTrimmedString(incomingMessage.author.userId) ?? undefined,
       authorName: readSlackAuthorName(incomingMessage),
     }
     aiLogger.info`Slack social-chat message received: channelId=${messageContext.channelId}, threadId=${messageContext.threadId}, messageId=${messageContext.messageId}, author=${messageContext.authorName ?? 'unknown'}, textLength=${messageContext.text.length}`
@@ -437,7 +226,7 @@ export function createSocialChatRuntime(params: {
       ? historyBeforeReply.filter((message) => message.cursor.id !== currentUserMessage.cursor.id)
       : historyBeforeReply
 
-    const workspaceProvider = getRuntimeAdapters().services?.workspaceProvider
+    const workspaceProvider = getRuntimeAdapters().workspaceProvider
     const workspace = workspaceProvider ? await workspaceProvider.getWorkspace(resolvedContext.workspaceId) : {}
     const lifecycleState = workspaceProvider ? await workspaceProvider.getLifecycleState?.(workspace) : undefined
     const workspaceProfileState = workspaceProvider
@@ -453,9 +242,10 @@ export function createSocialChatRuntime(params: {
 
     const promptContext = buildAgentPromptContext({
       workspaceName:
-        workspaceProfileState?.workspaceName ?? toOptionalTrimmedString((workspace as { name?: unknown }).name),
+        workspaceProfileState?.workspaceName ??
+        toOptionalTrimmedString((workspace as { name?: unknown }).name) ??
+        undefined,
       summaryBlock: workspaceProfileState?.summaryBlock,
-      structuredProfile: workspaceProfileState?.structuredProfile,
       promptSummary,
       userName: messageContext.authorName,
       recentDomainEvents,
@@ -492,23 +282,6 @@ export function createSocialChatRuntime(params: {
     ])
 
     let memoryBlock = ''
-    const runtimeConfig = getAgentRuntimeConfig({
-      agentId: socialAgentId,
-      workstreamMode: 'group',
-      mode: 'workstreamMode',
-      onboardingActive: lifecycleState?.bootstrapActive ?? false,
-      linearInstalled: false,
-      systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
-      preSeededMemoriesSection,
-      retrievedKnowledgeSection,
-      learnedSkillsSection,
-      additionalInstructionSections: [buildSocialChatIdentitySection(socialAgentDisplayName)],
-    }) as Record<string, unknown>
-    const agentFactory = createAgent[runtimeConfig.id as string]
-    if (typeof agentFactory !== 'function') {
-      throw new Error(`Social chat agent factory is not configured for ${String(runtimeConfig.id)}`)
-    }
-
     const consultParticipants = [
       ...new Set(
         (await socialChatConfig.getConsultParticipants?.({
@@ -520,7 +293,7 @@ export function createSocialChatRuntime(params: {
     ].filter((agentId) => agentId !== socialAgentId)
     const executedToolNames: string[] = []
 
-    const baseTools = withLoggedToolSet(
+    const baseTools = withLoggedSocialToolSet(
       await socialChatConfig.buildAgentTools(
         buildBuildToolsParams({
           agentId: socialAgentId,
@@ -542,7 +315,7 @@ export function createSocialChatRuntime(params: {
       },
     )
 
-    const transcript = buildThreadTranscript(historyBeforeReply)
+    const transcript = buildSocialChatThreadTranscript(historyBeforeReply)
     const runAbort = createServerRunAbortController()
 
     const consultSpecialistTool = createTool({
@@ -553,77 +326,66 @@ export function createSocialChatRuntime(params: {
           throw new Error(`Agent "${agentId}" is not an allowed social-chat specialist.`)
         }
 
-        let specialistMemoryBlock = ''
-        const specialistTools = withLoggedToolSet(
-          await socialChatConfig.buildAgentTools(
-            buildBuildToolsParams({
-              agentId,
-              context: resolvedContext,
-              workspaceIdString,
-              userIdString,
-              messageContext,
-              memoryBlock: specialistMemoryBlock,
-              onAppendMemoryBlock: (value: string) => {
-                specialistMemoryBlock = value
-              },
-            }),
-          ),
-          { agentId, channelId: messageContext.channelId, threadId: messageContext.threadId, executedToolNames },
-        )
-        const [specialistPreSeededMemories, specialistLearnedSkills] = await Promise.all([
-          memoryService.getTopMemories({
-            orgId: workspaceIdString,
-            agentName: agentId,
-            limit: PRESEEDED_MEMORY_LOOKUP_LIMIT,
-          }),
-          lifecycleState?.bootstrapActive
-            ? Promise.resolve(undefined)
-            : learnedSkillService
-                .retrieveForTurn({ orgId: workspaceIdString, agentId, query: task, limit: 3, minConfidence: 0.6 })
-                .catch((error) => {
-                  aiLogger.warn`Failed to retrieve learned skills for ${agentId}: ${error}`
-                  return undefined
+        const { result: specialistRun } = await runSpecialistSession({
+          initialMemoryBlock: '',
+          buildTools: async ({ memoryBlock: currentMemoryBlock, onAppendMemoryBlock }) =>
+            withLoggedSocialToolSet(
+              await socialChatConfig.buildAgentTools(
+                buildBuildToolsParams({
+                  agentId,
+                  context: resolvedContext,
+                  workspaceIdString,
+                  userIdString,
+                  messageContext,
+                  memoryBlock: currentMemoryBlock,
+                  onAppendMemoryBlock,
                 }),
-        ])
-
-        const specialistRuntimeConfig = getAgentRuntimeConfig({
-          agentId,
-          workstreamMode: 'group',
-          mode: 'fixedWorkstreamMode',
-          onboardingActive: lifecycleState?.bootstrapActive ?? false,
-          linearInstalled: false,
-          systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
-          preSeededMemoriesSection: specialistPreSeededMemories,
-          retrievedKnowledgeSection,
-          learnedSkillsSection: specialistLearnedSkills,
-          additionalInstructionSections: [
-            `You are supporting ${socialAgentDisplayName} in a Slack social-chat thread. Stay within your role.`,
-          ],
-        }) as Record<string, unknown>
-        const specialistFactory = createAgent[specialistRuntimeConfig.id as string]
-        if (typeof specialistFactory !== 'function') {
-          throw new Error(`Social specialist agent factory is not configured for ${String(specialistRuntimeConfig.id)}`)
-        }
-
-        const specialistAgent = specialistFactory({
-          mode: 'fixedWorkstreamMode',
-          tools: specialistTools,
-          extraInstructions: specialistRuntimeConfig.extraInstructions,
-          stopWhen: [stepCountIs(specialistRuntimeConfig.maxSteps as number)],
-        }) as SocialChatAgent
-        const specialistResponse = await specialistAgent.generate({
-          prompt: buildSpecialistPrompt({
-            requesterName: socialAgentDisplayName,
-            agentName: agentDisplayNames[agentId] ?? agentId,
-            task,
-            transcript,
-          }),
-          abortSignal: runAbort.signal,
+              ),
+              { agentId, channelId: messageContext.channelId, threadId: messageContext.threadId, executedToolNames },
+            ),
+          run: async ({ tools }) => {
+            const [specialistPreSeededMemories, specialistLearnedSkills] = await Promise.all([
+              memoryService.getTopMemories({
+                orgId: workspaceIdString,
+                agentName: agentId,
+                limit: PRESEEDED_MEMORY_LOOKUP_LIMIT,
+              }),
+              lifecycleState?.bootstrapActive
+                ? Promise.resolve(undefined)
+                : learnedSkillService
+                    .retrieveForTurn({ orgId: workspaceIdString, agentId, query: task, limit: 3, minConfidence: 0.6 })
+                    .catch((error) => {
+                      aiLogger.warn`Failed to retrieve learned skills for ${agentId}: ${error}`
+                      return undefined
+                    }),
+            ])
+
+            return await runSocialAgentTurn({
+              agentId,
+              mode: 'fixedWorkstreamMode',
+              workstreamMode: 'group',
+              onboardingActive: lifecycleState?.bootstrapActive ?? false,
+              linearInstalled: false,
+              systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
+              preSeededMemoriesSection: specialistPreSeededMemories,
+              retrievedKnowledgeSection,
+              learnedSkillsSection: specialistLearnedSkills,
+              userMessageText: task,
+              additionalInstructionSections: [
+                `You are supporting ${socialAgentDisplayName} in a Slack social-chat thread. Stay within your role.`,
+              ],
+              tools,
+              prompt: buildSpecialistSocialChatPrompt({
+                requesterName: socialAgentDisplayName,
+                agentName: agentDisplayNames[agentId] ?? agentId,
+                task,
+                transcript,
+              }),
+              abortSignal: runAbort.signal,
+            })
+          },
         })
-        const text = specialistResponse.text.trim()
-        if (!text) {
-          throw new Error(`Specialist ${agentId} returned an empty response.`)
-        }
+        const text = specialistRun.text
 
         return createAssistantMessage({ agentId, agentName: agentDisplayNames[agentId] ?? agentId, text })
       },
@@ -641,17 +403,22 @@ export function createSocialChatRuntime(params: {
       },
     })
 
-    const agent = agentFactory({
-      mode: 'workstreamMode',
-      tools: { ...baseTools, [CONSULT_SPECIALIST_TOOL_NAME]: consultSpecialistTool },
-      extraInstructions: runtimeConfig.extraInstructions,
-      stopWhen: [stepCountIs(runtimeConfig.maxSteps as number)],
-    }) as SocialChatAgent
-
     await thread.startTyping('Thinking...').catch(() => undefined)
     aiLogger.info`Slack social-chat generating reply: channelId=${messageContext.channelId}, threadId=${messageContext.threadId}`
-    const response = await agent.generate({
-      prompt: buildLeadAgentPrompt({
+    const leadRun = await runSocialAgentTurn({
+      agentId: socialAgentId,
+      mode: 'workstreamMode',
+      workstreamMode: 'group',
+      onboardingActive: lifecycleState?.bootstrapActive ?? false,
+      linearInstalled: false,
+      systemWorkspaceDetails: promptContext.systemWorkspaceDetails,
+      preSeededMemoriesSection,
+      retrievedKnowledgeSection,
+      learnedSkillsSection,
+      userMessageText: messageContext.text,
+      additionalInstructionSections: [buildSocialChatIdentitySection(socialAgentDisplayName)],
+      tools: { ...baseTools, [CONSULT_SPECIALIST_TOOL_NAME]: consultSpecialistTool },
+      prompt: buildLeadSocialChatPrompt({
         agentDisplayName: socialAgentDisplayName,
         channelId: messageContext.channelId,
         threadId: messageContext.threadId,
@@ -661,10 +428,7 @@ export function createSocialChatRuntime(params: {
       }),
       abortSignal: runAbort.signal,
     })
-    const responseText = response.text.trim()
-    if (!responseText) {
-      throw new Error('Social chat agent returned an empty response.')
-    }
+    const responseText = leadRun.text
 
     const replyMarkdown = buildSlackSocialReplyMarkdown({ replyMarkdown: responseText, executedToolNames })
     const sentMessage = await thread.post({ markdown: replyMarkdown })
@@ -690,7 +454,7 @@ export function createSocialChatRuntime(params: {
             {
               orgId: workspaceIdString,
               workstreamId: `social:slack:${messageContext.threadId}`,
-              sourceId: createCursorId({
+              sourceId: createSocialChatCursorId({
                 workspaceId: workspaceIdString,
                 threadId: messageContext.threadId,
                 messageId: messageContext.messageId,

package/src/runtime/specialist-runner.ts

@@ -0,0 +1,18 @@
+import type { ToolSet } from 'ai'
+
+export async function runSpecialistSession<TResult>(params: {
+  initialMemoryBlock: string
+  buildTools: (options: { memoryBlock: string; onAppendMemoryBlock: (value: string) => void }) => Promise<ToolSet>
+  run: (options: { tools: ToolSet; memoryBlock: string }) => Promise<TResult>
+}): Promise<{ result: TResult; memoryBlock: string }> {
+  let specialistMemoryBlock = params.initialMemoryBlock
+  const tools = await params.buildTools({
+    memoryBlock: specialistMemoryBlock,
+    onAppendMemoryBlock: (value) => {
+      specialistMemoryBlock = value
+    },
+  })
+
+  const result = await params.run({ tools, memoryBlock: specialistMemoryBlock })
+  return { result, memoryBlock: specialistMemoryBlock }
+}

package/src/runtime/workstream-chat-helpers.ts

@@ -7,6 +7,25 @@ export interface WorkstreamHistoryMessage {
   agentName?: string
 }
 
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : null
+}
+
+export function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value : undefined
+}
+
+export function readInstructionSections(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value
+    .filter((section): section is string => typeof section === 'string')
+    .map((section) => section.trim())
+    .filter((section) => section.length > 0)
+}
+
 function getAgentName(message: ChatMessageLike): string | undefined {
   const metadata = message.metadata
   if (!metadata || typeof metadata !== 'object') return undefined