@lota-sdk/core 0.1.5

package/src/tools/remember-memory.tool.ts

@@ -0,0 +1,85 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import type { RecordIdRef } from '../db/record-id'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { assessMemoryImportance, clampMemoryImportance } from '../services/memory-assessment.service'
+import { memoryService } from '../services/memory.service'
+import { safeEnqueue } from '../utils/async'
+
+const RememberMemoryInputSchema = z
+  .object({
+    content: z.string().min(1).describe('The memory to store.'),
+    targetScope: z.enum(['agent', 'global']).default('agent'),
+  })
+  .strict()
+
+export function createRememberMemoryTool({ orgId, agentName }: { orgId: RecordIdRef; agentName: string }) {
+  return tool({
+    description:
+      'Save a durable memory. Importance is scored automatically from memory significance. Use targetScope="agent" for role-specific memory, or targetScope="global" for organization-wide memory.',
+    inputSchema: RememberMemoryInputSchema,
+    execute: ({ content, targetScope }: z.infer<typeof RememberMemoryInputSchema>) => {
+      const trimmed = content.trim()
+      if (!trimmed) {
+        return { skipped: true, reason: 'Empty memory.' }
+      }
+
+      const orgIdString = recordIdToString(orgId, TABLES.ORGANIZATION)
+      void safeEnqueue(
+        async () => {
+          const assessment = await assessMemoryImportance({
+            content: trimmed,
+            targetScope,
+            tag: 'memory-importance-assessment',
+          })
+
+          if (assessment.classification === 'transient' && assessment.durability === 'ephemeral') {
+            return
+          }
+
+          const importance = Math.round(clampMemoryImportance(assessment.importance) * 100) / 100
+
+          if (targetScope === 'global') {
+            await memoryService.createOrganizationMemory({
+              orgId: orgIdString,
+              content: trimmed,
+              memoryType: 'fact',
+              importance,
+              metadata: {
+                source: 'agent_tool',
+                agentName,
+                memoryScope: 'global',
+                importanceSource: 'model_assessed',
+                durability: assessment.durability,
+                classification: assessment.classification,
+                rationale: assessment.rationale,
+              },
+            })
+            return
+          }
+
+          await memoryService.createAgentMemory({
+            orgId: orgIdString,
+            agentName,
+            content: trimmed,
+            memoryType: 'fact',
+            importance,
+            metadata: {
+              source: 'agent_tool',
+              memoryScope: 'agent',
+              importanceSource: 'model_assessed',
+              durability: assessment.durability,
+              classification: assessment.classification,
+              rationale: assessment.rationale,
+            },
+          })
+        },
+        { operationName: `remember memory (${targetScope})`, logPrefix: 'Background memoryRemember task failed' },
+      )
+
+      return { success: true, status: 'scheduled', scope: targetScope }
+    },
+  })
+}

package/src/tools/research-topic.tool.ts

@@ -0,0 +1,15 @@
+import { bifrostChatModel } from '../bifrost/bifrost'
+import { OPENROUTER_WEB_RESEARCH_MODEL_ID } from '../config/model-constants'
+import { createDelegatedAgentTool } from '../system-agents/delegated-agent-factory'
+import { RESEARCHER_PROMPT } from '../system-agents/researcher.agent'
+import { fetchWebpageTool } from './fetch-webpage.tool'
+import { searchWebTool } from './search-web.tool'
+
+export const researchTopicTool = createDelegatedAgentTool({
+  id: 'researchTopic',
+  description:
+    'Delegate a research task to a dedicated research agent that searches the web, fetches pages, and returns a synthesized markdown report. Call multiple instances in parallel for broad research across different topics.',
+  model: bifrostChatModel(OPENROUTER_WEB_RESEARCH_MODEL_ID),
+  instructions: RESEARCHER_PROMPT,
+  tools: { searchWeb: searchWebTool.create(), fetchWebpage: fetchWebpageTool.create() },
+})

package/src/tools/search-tools.ts

@@ -0,0 +1,55 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import { isAgentName } from '../config/agent-defaults'
+import type { RecordIdRef } from '../db/record-id'
+import { memoryService } from '../services/memory.service'
+import { workstreamMessageService } from '../services/workstream-message.service'
+
+const CONVERSATION_SEARCH_RESULT_LIMIT = 20
+const MemorySearchInputSchema = z.object({ query: z.string().min(1) }).strict()
+const ConversationSearchInputSchema = z.object({ query: z.string().min(1), type: z.enum(['user', 'agent']) }).strict()
+
+export function createMemorySearchTool(
+  orgIdString: string,
+  agentName?: string,
+  options?: { fastMode?: boolean; allowMultiScopeRerank?: boolean },
+) {
+  return tool({
+    description: 'Search organization and agent memories relevant to a query.',
+    inputSchema: MemorySearchInputSchema,
+    execute: async ({ query }: z.infer<typeof MemorySearchInputSchema>) => {
+      const normalizedQuery = query.trim()
+      const retrieval = await memoryService.searchAllMemoriesBatched({
+        orgId: orgIdString,
+        agentName: isAgentName(agentName) ? (agentName as string) : undefined,
+        query: normalizedQuery,
+        ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
+        ...(typeof options?.allowMultiScopeRerank === 'boolean'
+          ? { allowMultiScopeRerank: options.allowMultiScopeRerank }
+          : {}),
+      })
+      const reminder = `Remember: you searched for "${normalizedQuery}". Use the highest-relevance retrieved lines above to answer.`
+
+      return { query: normalizedQuery, retrieval, reminder }
+    },
+  })
+}
+
+export function createConversationSearchTool(workstreamId: RecordIdRef) {
+  return tool({
+    description: 'Search prior chat messages by role and query text.',
+    inputSchema: ConversationSearchInputSchema,
+    execute: async ({ query, type }: z.infer<typeof ConversationSearchInputSchema>) => {
+      const normalizedQuery = query.trim()
+      const results = await workstreamMessageService.searchMessages({
+        workstreamId,
+        role: type === 'user' ? 'user' : 'assistant',
+        query: normalizedQuery,
+        limit: CONVERSATION_SEARCH_RESULT_LIMIT,
+      })
+
+      return { query: normalizedQuery, type, count: results.length, results }
+    },
+  })
+}

package/src/tools/search-web.tool.ts

@@ -0,0 +1,175 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../ai/definitions'
+import type { Citation } from '../services/workstream.types'
+import { withTimeout } from '../utils/async'
+import { readStringField, truncateOptionalText } from '../utils/string'
+import { getFirecrawlClient } from './firecrawl-client'
+
+const TOOL_TIMEOUT_MS = 30_000
+const SourceSchema = z.enum(['web', 'news', 'images'])
+const MAX_RESULTS_PER_SOURCE = 4
+const MAX_SNIPPET_CHARS = 320
+
+function readMetadata(item: unknown): Record<string, unknown> {
+  if (!item || typeof item !== 'object') return {}
+  const metadata = (item as Record<string, unknown>).metadata
+  return metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+    ? (metadata as Record<string, unknown>)
+    : {}
+}
+
+function readSearchItemSnippet(record: Record<string, unknown>, metadata: Record<string, unknown>): string | undefined {
+  return truncateOptionalText(
+    [
+      readStringField(record, 'description'),
+      readStringField(record, 'snippet'),
+      readStringField(record, 'summary'),
+      readStringField(record, 'markdown'),
+      readStringField(metadata, 'description'),
+      readStringField(metadata, 'snippet'),
+      readStringField(metadata, 'summary'),
+    ].find((value) => typeof value === 'string' && value.trim().length > 0),
+    MAX_SNIPPET_CHARS,
+  )
+}
+
+function summarizeSearchItem(item: unknown): Record<string, string> | null {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+
+  const record = item as Record<string, unknown>
+  const metadata = readMetadata(item)
+  const url = extractUrlFromSearchItem(item)
+
+  if (!url) return null
+
+  const title = truncateOptionalText(readStringField(record, 'title') ?? readStringField(metadata, 'title'), 140)
+  const snippet = readSearchItemSnippet(record, metadata)
+  const publishedAt = truncateOptionalText(
+    readStringField(record, 'publishedDate') ??
+      readStringField(record, 'publishedAt') ??
+      readStringField(metadata, 'publishedDate') ??
+      readStringField(metadata, 'publishedAt'),
+    80,
+  )
+  const siteName = truncateOptionalText(
+    readStringField(record, 'siteName') ?? readStringField(metadata, 'siteName'),
+    80,
+  )
+  const imageUrl = truncateOptionalText(
+    readStringField(record, 'imageUrl') ?? readStringField(metadata, 'imageUrl') ?? readStringField(metadata, 'image'),
+    500,
+  )
+
+  return {
+    url,
+    ...(title ? { title } : {}),
+    ...(snippet ? { snippet } : {}),
+    ...(publishedAt ? { publishedAt } : {}),
+    ...(siteName ? { siteName } : {}),
+    ...(imageUrl ? { imageUrl } : {}),
+  }
+}
+
+function summarizeSearchItems(items: unknown[] | undefined): Record<string, unknown> {
+  const summarized = (items ?? []).map((item) => summarizeSearchItem(item)).filter((item) => item !== null)
+
+  return { total: summarized.length, items: summarized.slice(0, MAX_RESULTS_PER_SOURCE) }
+}
+
+function extractUrlFromSearchItem(item: unknown): string | undefined {
+  if (!item || typeof item !== 'object') return undefined
+
+  const record = item as Record<string, unknown>
+  if (typeof record.url === 'string' && record.url.trim().length > 0) {
+    return record.url.trim()
+  }
+  if (typeof record.imageUrl === 'string' && record.imageUrl.trim().length > 0) {
+    return record.imageUrl.trim()
+  }
+
+  const metadata = record.metadata
+  if (metadata && typeof metadata === 'object') {
+    const metadataRecord = metadata as Record<string, unknown>
+    if (typeof metadataRecord.url === 'string' && metadataRecord.url.trim().length > 0) {
+      return metadataRecord.url.trim()
+    }
+    if (typeof metadataRecord.sourceURL === 'string' && metadataRecord.sourceURL.trim().length > 0) {
+      return metadataRecord.sourceURL.trim()
+    }
+    if (typeof metadataRecord.imageUrl === 'string' && metadataRecord.imageUrl.trim().length > 0) {
+      return metadataRecord.imageUrl.trim()
+    }
+  }
+
+  return undefined
+}
+
+function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): Citation[] {
+  const seen = new Set<string>()
+  const citations: Citation[] = []
+  const retrievedAt = new Date().toISOString()
+
+  const append = (items: unknown[] | undefined) => {
+    if (!items) return
+    for (const item of items) {
+      const url = extractUrlFromSearchItem(item)
+      if (!url || seen.has(url)) continue
+      seen.add(url)
+      citations.push({ source: 'web', sourceId: url, retrievedAt })
+    }
+  }
+
+  append(results.web)
+  append(results.news)
+  append(results.images)
+
+  return citations
+}
+
+export const searchWebTool = {
+  name: 'searchWeb',
+  create: () =>
+    tool({
+      description: 'Search the web for real-time information.',
+      inputSchema: z
+        .object({
+          query: z.string().min(1, 'Query is required'),
+          limit: z.number().int().min(1).max(10).optional(),
+          sources: z.array(SourceSchema).optional(),
+          location: z.string().optional(),
+          tbs: z.string().optional(),
+        })
+        .strict(),
+      execute: async ({
+        query,
+        limit,
+        sources,
+        location,
+        tbs,
+      }: {
+        query: string
+        limit?: number
+        sources?: ('web' | 'news' | 'images')[]
+        location?: string
+        tbs?: string
+      }) => {
+        const results = await withTimeout(
+          getFirecrawlClient().search(query, { limit, sources, location, tbs }),
+          TOOL_TIMEOUT_MS,
+          'Web search',
+        )
+
+        return {
+          query,
+          results: {
+            web: summarizeSearchItems(results.web),
+            news: summarizeSearchItems(results.news),
+            images: summarizeSearchItems(results.images),
+          },
+          citations: buildWebCitations(results),
+        }
+      },
+    }),
+} as const satisfies ToolDefinition<void>

package/src/tools/team-think.tool.ts

@@ -0,0 +1,125 @@
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import { stepCountIs } from 'ai'
+import type { ToolSet } from 'ai'
+
+import { createAgent, getAgentRuntimeConfig } from '../config/agent-defaults'
+import { aiLogger } from '../config/logger'
+import type { RecordIdRef } from '../db/record-id'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { mergeInstructionSections } from '../runtime/instruction-sections'
+import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import { createConsultTeamTool as createConsultTeamToolSdk } from '../runtime/team-consultation-orchestrator'
+import type { DefaultRepoSections, TeamConsultationParticipantRunner } from '../runtime/team-consultation-orchestrator'
+import { buildTeamConsultationResponseGuard } from '../runtime/team-consultation-prompts'
+import type { ReadableUploadMetadata } from '../services/attachment.service'
+
+async function buildTeamThinkAgentTools(params: Record<string, unknown>): Promise<{ tools: Record<string, unknown> }> {
+  const builder = getRuntimeAdapters().workstream?.buildTeamThinkAgentTools
+  if (!builder) {
+    return { tools: {} }
+  }
+
+  const result = await builder(params as never)
+  return { tools: result.tools as Record<string, unknown> }
+}
+
+const TEAM_THINK_AGENT_MAX_RETRIES = 4
+
+export function createTeamThinkTool(params: {
+  historyMessages: ChatMessage[]
+  latestUserMessageId: string
+  orgId: RecordIdRef
+  userId: RecordIdRef
+  workstreamId: RecordIdRef
+  githubInstalled: boolean
+  availableUploads: ReadableUploadMetadata[]
+  provideRepoTool: boolean
+  defaultRepoSectionsByAgent: Record<string, DefaultRepoSections | undefined>
+  reasoningProfile: 'fast' | 'standard' | 'deep'
+  systemWorkspaceDetails?: string
+  getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
+  retrievedKnowledgeSection?: string
+  additionalInstructionSections?: string[]
+  getAdditionalInstructionSections?: () => Promise<string[] | undefined>
+  context?: unknown
+  toolProviders?: ToolSet
+  abortSignal: AbortSignal
+}) {
+  const participantRunner: TeamConsultationParticipantRunner = {
+    async buildParticipantAgent(agentId, runParams) {
+      const dynamicInstructionSections = await params.getAdditionalInstructionSections?.()
+      const config = getAgentRuntimeConfig({
+        agentId,
+        workstreamMode: 'group' as const,
+        mode: 'fixedWorkstreamMode',
+        onboardingActive: false,
+        linearInstalled: false,
+        reasoningProfile: runParams.reasoningProfile,
+        systemWorkspaceDetails: runParams.systemWorkspaceDetails,
+        preSeededMemoriesSection: runParams.preSeededMemoriesSection,
+        retrievedKnowledgeSection: runParams.retrievedKnowledgeSection,
+        additionalInstructionSections: mergeInstructionSections(
+          dynamicInstructionSections,
+          params.additionalInstructionSections,
+        ),
+        responseGuardSection: buildTeamConsultationResponseGuard({ agentId, task: runParams.task }),
+      })
+      const { tools } = await buildTeamThinkAgentTools({
+        agentId,
+        workspaceId: params.orgId,
+        userId: params.userId,
+        workspaceIdString: recordIdToString(params.orgId, TABLES.ORGANIZATION),
+        workstreamId: params.workstreamId,
+        githubInstalled: params.githubInstalled,
+        provideRepoTool: params.provideRepoTool,
+        availableUploads: params.availableUploads,
+        defaultRepoSections: params.defaultRepoSectionsByAgent[agentId],
+        context: params.context,
+        toolProviders: params.toolProviders,
+      })
+      const agentConfig = config as Record<string, unknown>
+      const agentFactory = createAgent as unknown as Record<string, (...args: unknown[]) => unknown>
+      const agent = agentFactory[agentConfig.id as string]({
+        mode: 'fixedWorkstreamMode',
+        tools,
+        extraInstructions: agentConfig.extraInstructions,
+        maxRetries: TEAM_THINK_AGENT_MAX_RETRIES,
+        stopWhen: [stepCountIs(agentConfig.maxSteps as number)],
+      })
+      const observer = {
+        run: async <T>(fn: () => T | Promise<T>): Promise<T> => fn(),
+        recordError: (error: unknown) => {
+          aiLogger.error`Team-think participant failed (${agentId}): ${error}`
+        },
+        recordAbort: (error: unknown) => {
+          aiLogger.info`Team-think participant aborted (${agentId}): ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        },
+      }
+      return {
+        agent: agent as Awaited<ReturnType<TeamConsultationParticipantRunner['buildParticipantAgent']>>['agent'],
+        observer,
+      }
+    },
+  }
+
+  return createConsultTeamToolSdk({
+    historyMessages: params.historyMessages,
+    latestUserMessageId: params.latestUserMessageId,
+    availableUploads: params.availableUploads,
+    defaultRepoSectionsByAgent: params.defaultRepoSectionsByAgent,
+    reasoningProfile: params.reasoningProfile,
+    systemWorkspaceDetails: params.systemWorkspaceDetails,
+    getPreSeededMemoriesSection: params.getPreSeededMemoriesSection,
+    retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+    abortSignal: params.abortSignal,
+    participantRunner,
+    onReadError: (agentId, error) => {
+      if (!(error instanceof Error && error.name === 'AbortError')) {
+        aiLogger.error`UI message read failed for team-think participant ${agentId}: ${error}`
+      }
+    },
+  })
+}

package/src/tools/tool-contract.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod'
+
+/** @lintignore */
+export const MutatingApprovalSchema = {
+  approvalReason: z.string().trim().min(1, 'approvalReason is required').max(500),
+  approvalToken: z.string().trim().min(1, 'approvalToken is required').max(500),
+  approvalMessageId: z.string().trim().min(1).max(200).optional(),
+} as const
+
+/** @lintignore */
+export const CitationSchema = z
+  .object({
+    source: z.string().trim().min(1),
+    sourceId: z.string().trim().min(1),
+    version: z.string().trim().min(1).optional(),
+    retrievedAt: z.iso.datetime(),
+  })
+  .strict()
+
+/** @lintignore */
+export type Citation = z.infer<typeof CitationSchema>

package/src/tools/user-questions.tool.ts

@@ -0,0 +1,18 @@
+import { USER_QUESTIONS_TOOL_NAME, UserQuestionsArgsSchema } from '@lota-sdk/shared/schemas/tools'
+import type { UserQuestionsArgs } from '@lota-sdk/shared/schemas/tools'
+import { tool } from 'ai'
+
+import type { ToolDefinition } from '../ai/definitions'
+
+export const userQuestionsTool = {
+  name: USER_QUESTIONS_TOOL_NAME,
+  create: () =>
+    tool({
+      description:
+        'Present structured questions to the user and wait for their response. The chat UI already renders the questions, so do not repeat them as assistant text. Use this when you need clarification or input from the user. Execution stops after this tool is called.',
+      inputSchema: UserQuestionsArgsSchema,
+      execute: async (_args: UserQuestionsArgs) => {
+        return 'Questions have been presented to the user in the chat UI. Do NOT restate them in text, and do NOT generate further text or tool calls. Your turn is complete.'
+      },
+    }),
+} as const satisfies ToolDefinition<void>

package/src/utils/async.ts

@@ -0,0 +1,50 @@
+import { getErrorMessage } from './error'
+
+class TimeoutError extends Error {
+  constructor(operation: string, ms: number) {
+    super(`${operation} timed out after ${ms}ms`)
+    this.name = 'TimeoutError'
+  }
+}
+
+export async function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => {
+    controller.abort()
+  }, ms)
+
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        controller.signal.addEventListener('abort', () => {
+          reject(new TimeoutError(operation, ms))
+        })
+      }),
+    ])
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+export function createSafeEnqueue(logger: { warn: (message: string) => void }) {
+  return function safeEnqueue<T>(
+    operation: () => Promise<T>,
+    options: { operationName: string; onError?: (error: unknown) => void; logPrefix?: string },
+  ): Promise<T | void> {
+    const { operationName, onError, logPrefix = 'Failed to enqueue' } = options
+
+    return operation().catch((error: unknown) => {
+      logger.warn(`${logPrefix} ${operationName} (non-fatal): ${getErrorMessage(error)}`)
+      onError?.(error)
+    })
+  }
+}
+
+const _defaultSafeEnqueue = createSafeEnqueue({ warn: console.warn })
+export function safeEnqueue<T>(
+  operation: () => T | Promise<T>,
+  options: { operationName: string; onError?: (error: unknown) => void; logPrefix?: string },
+): Promise<T | void> {
+  return _defaultSafeEnqueue(() => Promise.resolve(operation()), options)
+}

package/src/utils/date-time.ts

@@ -0,0 +1,34 @@
+export function toIsoDateTimeString(value: unknown): string {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  // Assume API boundaries already use ISO strings.
+  if (typeof value === 'string') {
+    return value
+  }
+
+  // Support unix timestamps (seconds or milliseconds).
+  if (typeof value === 'number') {
+    const millis = value < 1_000_000_000_000 ? value * 1000 : value
+    return new Date(millis).toISOString()
+  }
+
+  // Support objects that expose toISOString (e.g., SurrealDB temporal types).
+  if (value && typeof value === 'object') {
+    const maybeToIso = (value as { toISOString?: unknown }).toISOString
+    if (typeof maybeToIso === 'function') {
+      return (value as { toISOString: () => string }).toISOString()
+    }
+  }
+
+  return String(value)
+}
+
+export function toOptionalIsoDateTimeString(value: unknown): string | undefined {
+  if (value === null || value === undefined || value === '') {
+    return undefined
+  }
+
+  return toIsoDateTimeString(value)
+}

package/src/utils/error.ts

@@ -0,0 +1,10 @@
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,28 @@
+export class AppError extends Error {
+  public readonly code: string
+  public readonly statusCode: number
+
+  constructor(message: string, code: string, statusCode: number) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = code
+    this.statusCode = statusCode
+    Error.captureStackTrace(this, this.constructor)
+  }
+
+  public toResponse() {
+    return { status: this.statusCode, body: { error: { code: this.code, message: this.message } } }
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Resource not found') {
+    super(message, 'NOT_FOUND', 404)
+  }
+}
+
+export class BadRequestError extends AppError {
+  constructor(message = 'Bad request') {
+    super(message, 'BAD_REQUEST', 400)
+  }
+}