@lota-sdk/core 0.1.13 → 0.1.15

package/src/services/workstream-turn.ts

@@ -4,8 +4,8 @@ import { createUIMessageStream } from 'ai'
 import { lotaDebugLogger } from '../config/debug-logger'
 import { hasApprovalRespondedParts, isApprovalContinuationRequest } from '../runtime/approval-continuation'
 import { wrapResponseWithKeepalive } from '../utils/sse-keepalive'
-import { prepareWorkstreamRunCore } from './workstream-turn-preparation'
-import type { WorkstreamTurnParams, WorkstreamApprovalContinuationParams } from './workstream-turn-preparation'
+import { prepareWorkstreamRunCore } from './workstream-turn-preparation.service'
+import type { WorkstreamTurnParams, WorkstreamApprovalContinuationParams } from './workstream-turn-preparation.service'
 
 export { hasApprovalRespondedParts, isApprovalContinuationRequest }
 export { wrapResponseWithKeepalive }

package/src/services/workstream.service.ts

@@ -1,7 +1,8 @@
-import { WORKSTREAM } from '@lota-sdk/shared'
+import { WORKSTREAM, sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
 import { BoundQuery, RecordId, StringRecordId, surql } from 'surrealdb'
 
 import { agentDisplayNames, getCoreWorkstreamProfile, isAgentName } from '../config/agent-defaults'
+import { serverLogger } from '../config/logger'
 import { getWorkstreamBootstrapConfig } from '../config/workstream-defaults'
 import { BaseService } from '../db/base.service'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -24,7 +25,7 @@ import { toIsoDateTimeString } from '../utils/date-time'
 import { chatRunRegistry } from './chat-run-registry.service'
 import { contextCompactionService } from './context-compaction.service'
 import { workstreamMessageService } from './workstream-message.service'
-import { WorkstreamSchema, WorkstreamStatusSchema } from './workstream.types'
+import { WorkstreamSchema } from './workstream.types'
 import type { NormalizedWorkstream, WorkstreamRecord } from './workstream.types'
 
 // Uses SurrealQL directly to keep pagination/order logic close to queries.
@@ -368,15 +369,16 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   async listWorkstreams(
     userId: RecordIdRef,
     orgId: RecordIdRef,
-    options: { mode: string; core?: boolean; take?: number; page?: number; includeArchived: boolean },
+    options: { mode: string; core?: boolean; take?: number; page?: number; includeArchived?: boolean },
   ): Promise<{ workstreams: NormalizedWorkstream[]; hasMore: boolean }> {
     const core = options.core === true
+    const includeArchived = options.includeArchived ?? false
     if (options.mode === 'direct' && core) {
       throw new Error('Direct workstreams cannot be queried as core workstreams')
     }
 
     if (options.mode === 'direct' || core) {
-      const query = options.includeArchived
+      const query = includeArchived
         ? LIST_ALL_WORKSTREAMS_BY_MODE_QUERY
         : LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY
       const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
@@ -389,7 +391,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
 
     const take = options.take ?? WORKSTREAM.DEFAULT_PAGE_LIMIT
     const page = options.page ?? 1
-    const query = options.includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
+    const query = includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
     const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
       new BoundQuery(query, {
         userId,
@@ -467,7 +469,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   }
 
   async updateStatus(workstreamId: RecordIdRef, status: string): Promise<NormalizedWorkstream> {
-    const validStatus = WorkstreamStatusSchema.parse(status)
+    const validStatus = sdkWorkstreamStatusSchema.parse(status)
     const existing = await this.getById(workstreamId)
     this.assertMutableWorkstream(existing, validStatus === 'archived' ? 'archive' : 'unarchive')
     const workstream = await this.update(workstreamId, { status: validStatus })
@@ -543,11 +545,19 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return false
   }
 
-  async setCompacting(workstreamId: RecordIdRef, value: boolean): Promise<void> {
+  async markCompacting(workstreamId: RecordIdRef): Promise<void> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
     await databaseService.query<unknown>(surql`
       UPDATE ONLY ${workstreamRef}
-      SET isCompacting = ${value}
+      SET isCompacting = ${true}
+    `)
+  }
+
+  async clearCompacting(workstreamId: RecordIdRef): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET isCompacting = ${false}
     `)
   }
 
@@ -566,7 +576,9 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     await this.update(workstreamRef, { memoryBlock: serialized })
 
     if (updatedEntries.length >= MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES) {
-      void this.compactMemoryBlock(workstreamRef).catch(() => {})
+      void this.compactMemoryBlock(workstreamRef).catch((err: unknown) => {
+        serverLogger.warn`Memory block compaction failed for ${workstreamRef}: ${err}`
+      })
     }
 
     return this.formatMemoryBlockForPrompt({
@@ -612,7 +624,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     orgId: RecordIdRef
     excludeWorkstreamId?: RecordIdRef
     limit: number
-  }) {
+  }): Promise<NormalizedWorkstream[]> {
     let excludeCondition = ''
     const vars: Record<string, unknown> = { userId, orgId, limit }
 

package/src/services/workstream.types.ts

@@ -1,16 +1,7 @@
+import { sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
 import { z } from 'zod'
 
-export interface Citation {
-  title?: string
-  url?: string
-  snippet?: string
-  source?: string
-  sourceId?: string
-  retrievedAt?: string
-}
-
 const WorkstreamModeSchema = z.enum(['direct', 'group'])
-export const WorkstreamStatusSchema = z.enum(['regular', 'archived'])
 const CoreWorkstreamTypeSchema = z.string()
 
 export interface NormalizedWorkstream {
@@ -20,7 +11,7 @@ export interface NormalizedWorkstream {
   mode: 'direct' | 'group'
   core: boolean
   coreType?: string
-  nameGenerated: boolean
+  nameGenerated: boolean // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
   isRunning: boolean
   isCompacting: boolean
   agentId?: string | null
@@ -32,27 +23,27 @@ export interface NormalizedWorkstream {
 }
 
 export const WorkstreamSchema = z.object({
-  id: z.any(), // RecordId
+  id: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
   mode: WorkstreamModeSchema.optional().default('group'),
   core: z.boolean().optional().default(false),
   coreType: CoreWorkstreamTypeSchema.nullish(),
   agentId: z.string().nullish(),
   title: z.string().nullish(),
-  status: WorkstreamStatusSchema.nullish(),
+  status: sdkWorkstreamStatusSchema.nullish(),
   memoryBlock: z.string().nullish(),
   memoryBlockSummary: z.string().nullish(),
   activeRunId: z.string().nullish(),
   activeStreamId: z.string().nullish(),
   compactionSummary: z.string().nullish(),
   lastCompactedMessageId: z.string().nullish(),
-  nameGenerated: z.boolean().optional().default(false),
+  nameGenerated: z.boolean().optional().default(false), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
   isCompacting: z.boolean().optional(),
   state: z.unknown().optional(),
   turnCount: z.number().int().optional().default(0),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
-  userId: z.any(), // RecordId
-  organizationId: z.any(), // RecordId
+  userId: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
+  organizationId: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
 })
 
 export type WorkstreamRecord = z.infer<typeof WorkstreamSchema>

package/src/storage/attachment-storage.service.ts

@@ -15,14 +15,14 @@ import type {
   ReadableUploadMetadata,
   ReadableUploadPageMode,
   ReadableUploadPagePart,
-} from './attachments.types'
+} from './attachment-types'
 import {
   buildOrganizationDocumentStorageKey,
   buildUploadStorageKey,
   buildUploadStoragePrefix,
   readNonNegativeInteger,
   readRecord,
-} from './attachments.utils'
+} from './attachment-utils'
 
 const READ_FILE_PARTS_PAGES_PER_PART = 25
 
@@ -386,7 +386,7 @@ export function getAttachmentStorageService(): AttachmentStorageService {
 }
 
 export const attachmentStorageService = new Proxy({} as AttachmentStorageService, {
-  get(_target, prop: string) {
-    return (getAttachmentStorageService() as unknown as Record<string, unknown>)[prop]
+  get(_target, prop: string): unknown {
+    return Reflect.get(getAttachmentStorageService(), prop)
   },
 })

package/src/storage/{attachments.utils.ts → attachment-utils.ts}

@@ -48,10 +48,7 @@ export function buildOrganizationDocumentStorageKey(params: {
   return `${buildOrganizationDocumentStoragePrefix({ orgId: params.orgId, namespace: params.namespace })}${relativePath || 'document.txt'}`
 }
 
-export function readRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
-  return value as Record<string, unknown>
-}
+export { readRecord } from '../utils/string'
 
 export function readNonNegativeInteger(value: unknown): number | null {
   return Number.isInteger(value) && typeof value === 'number' && value >= 0 ? value : null

package/src/storage/index.ts

@@ -1,10 +1,10 @@
 export * from './attachment-parser'
 export * from './attachment-storage.service'
 export * from './generated-document-storage.service'
-export type { MessagePartLike, ReadableUploadPageMode, ReadableUploadPagePart } from './attachments.types'
+export type { MessagePartLike, ReadableUploadPageMode, ReadableUploadPagePart } from './attachment-types'
 export {
   buildOrganizationDocumentStorageKey,
   buildUploadStorageKey,
   buildUploadStoragePrefix,
   readNonNegativeInteger,
-} from './attachments.utils'
+} from './attachment-utils'

package/src/system-agents/{context-compacter.agent.ts → context-compaction.agent.ts}

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-const contextCompacterPrompt = `<agent-instructions>
+const CONTEXT_COMPACTION_PROMPT = `<agent-instructions>
 You are a **Context Compacter** that produces both:
 1) a dense but shorter summary of prior context
 2) a structured state delta for durable execution continuity
@@ -36,11 +36,11 @@ Return valid data for:
 </output-format>
 </agent-instructions>`
 
-export function createContextCompacterAgent(options: CreateHelperToolLoopAgentOptions) {
+export function createContextCompactionAgent(options: CreateHelperToolLoopAgentOptions) {
   return new ToolLoopAgent({
-    id: 'context-compacter',
+    id: 'context-compaction',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, { instructions: contextCompacterPrompt }),
+    ...resolveHelperAgentOptions(options, { instructions: CONTEXT_COMPACTION_PROMPT }),
   })
 }

package/src/system-agents/delegated-agent-factory.ts

@@ -79,6 +79,7 @@ const TERMINATION_SUFFIX = `
 When your analysis is complete, return your final answer directly as markdown text. Do not leave the task unfinished or end on a tool result without a final response.
 </termination>`
 
+const DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS = 4096
 const MAX_RETAINED_AGENT_MESSAGES = 10
 const MAX_NON_SUBSTANTIVE_AGENT_RESULT_ATTEMPTS = 2
 const NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT =
@@ -164,7 +165,7 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
-              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
               ...(typeof temperature === 'number' ? { temperature } : {}),
               stopWhen: [stepCountIs(maxSteps)],
               prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
@@ -205,7 +206,7 @@ export function createDelegatedAgentToolWithContext<TContext>(
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
-              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
               ...(typeof temperature === 'number' ? { temperature } : {}),
               stopWhen: [stepCountIs(maxSteps)],
               prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),

package/src/system-agents/index.ts

@@ -1,4 +1,12 @@
 export * from './agent-result'
+export * from './context-compaction.agent'
 export * from './delegated-agent-factory'
 export * from './helper-agent-options'
+export * from './memory-reranker.agent'
+export * from './memory.agent'
 export * from './recent-activity-title-refiner.agent'
+export * from './regular-chat-memory-digest.agent'
+export * from './researcher.agent'
+export * from './skill-extractor.agent'
+export * from './skill-manager.agent'
+export * from './title-generator.agent'

package/src/system-agents/memory-reranker.agent.ts

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-export const memoryRerankerPrompt = `<agent-instructions>
+export const MEMORY_RERANKER_PROMPT = `<agent-instructions>
 You are a **Memory Reranker** that selects and organizes the most relevant memories for a user query.
 
 <task>

package/src/system-agents/memory.agent.ts

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-export const orgMemoryPrompt = `<agent-instructions>
+export const ORG_MEMORY_PROMPT = `<agent-instructions>
 You are an **Organization Fact Extractor** that captures only durable, explicitly stated organization facts.
 
 <task>

package/src/system-agents/recent-activity-title-refiner.agent.ts

@@ -45,7 +45,7 @@ Return only the title text. No quotes, labels, JSON, markdown, or explanation.
 </agent-instructions>`
 }
 
-export const recentActivityTitleRefinerPrompt = `<agent-instructions>
+export const RECENT_ACTIVITY_TITLE_REFINER_PROMPT = `<agent-instructions>
 You are the lead agent writing the visible title for a recent activity item.
 
 <goal>

package/src/tools/execution-plan.tool.ts

@@ -11,9 +11,13 @@ import { tool } from 'ai'
 import type { RecordIdRef } from '../db/record-id'
 import { executionPlanService } from '../services/execution-plan.service'
 
+function isExecutionPlanResult(value: unknown): value is ExecutionPlanToolResultData {
+  return value !== null && value !== undefined && typeof value === 'object' && 'hasPlan' in value
+}
+
 function getLatestExecutionPlanToolResult(output: unknown): ExecutionPlanToolResultData | undefined {
-  if (output && typeof output === 'object' && 'hasPlan' in output) {
-    return output as ExecutionPlanToolResultData
+  if (isExecutionPlanResult(output)) {
+    return output
   }
 
   if (Array.isArray(output)) {

package/src/tools/fetch-webpage.tool.ts

@@ -2,10 +2,10 @@ 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'
+import type { WebCitation } from './tool-contracts'
 
 const TOOL_TIMEOUT_MS = 30_000
 const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
@@ -14,6 +14,11 @@ const MAX_SUMMARY_CHARS = 1_200
 const MAX_LINKS = 25
 const MAX_IMAGES = 10
 
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
 function readStringList(record: Record<string, unknown>, key: string, maxItems: number): string[] {
   const value = record[key]
   if (!Array.isArray(value)) return []
@@ -24,15 +29,12 @@ function readStringList(record: Record<string, unknown>, key: string, maxItems:
 }
 
 function summarizeDocument(url: string, document: unknown): Record<string, unknown> {
-  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+  const record = toRecord(document)
+  if (!record) {
     return { url }
   }
 
-  const record = document as Record<string, unknown>
-  const metadata =
-    record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
-      ? (record.metadata as Record<string, unknown>)
-      : {}
+  const metadata = toRecord(record.metadata) ?? {}
 
   const canonicalUrl = truncateOptionalText(
     readStringField(metadata, 'url') ?? readStringField(metadata, 'sourceURL') ?? readStringField(record, 'url') ?? url,
@@ -51,8 +53,8 @@ function summarizeDocument(url: string, document: unknown): Record<string, unkno
             return truncateOptionalText(image, 500)
           }
 
-          if (image && typeof image === 'object' && !Array.isArray(image)) {
-            const imageRecord = image as Record<string, unknown>
+          const imageRecord = toRecord(image)
+          if (imageRecord) {
             return truncateOptionalText(readStringField(imageRecord, 'src') ?? readStringField(imageRecord, 'url'), 500)
           }
 
@@ -73,18 +75,18 @@ function summarizeDocument(url: string, document: unknown): Record<string, unkno
   }
 }
 
-function buildFetchCitations(url: string, document: unknown): Citation[] {
+function buildFetchCitations(url: string, document: unknown): WebCitation[] {
   const fallbackUrl = url.trim()
   let sourceId = fallbackUrl
 
-  if (document && typeof document === 'object') {
-    const metadata = (document as Record<string, unknown>).metadata
-    if (metadata && typeof metadata === 'object') {
-      const record = metadata as Record<string, unknown>
-      if (typeof record.url === 'string' && record.url.trim().length > 0) {
-        sourceId = record.url.trim()
-      } else if (typeof record.sourceURL === 'string' && record.sourceURL.trim().length > 0) {
-        sourceId = record.sourceURL.trim()
+  const docRecord = toRecord(document)
+  if (docRecord) {
+    const metadataRecord = toRecord(docRecord.metadata)
+    if (metadataRecord) {
+      if (typeof metadataRecord.url === 'string' && metadataRecord.url.trim().length > 0) {
+        sourceId = metadataRecord.url.trim()
+      } else if (typeof metadataRecord.sourceURL === 'string' && metadataRecord.sourceURL.trim().length > 0) {
+        sourceId = metadataRecord.sourceURL.trim()
       }
     }
   }

package/src/tools/index.ts

@@ -5,8 +5,8 @@ export * from './memory-block.tool'
 export * from './read-file-parts.tool'
 export * from './remember-memory.tool'
 export * from './research-topic.tool'
-export * from './search-tools'
+export * from './search.tool'
 export * from './search-web.tool'
 export * from './team-think.tool'
-export * from './tool-contract'
+export * from './tool-contracts'
 export * from './user-questions.tool'

package/src/tools/read-file-parts.tool.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
 import { attachmentStorageService } from '../storage/attachment-storage.service'
-import type { ReadableUploadMetadata } from '../storage/attachments.types'
+import type { ReadableUploadMetadata } from '../storage/attachment-types'
 
 const PAGES_PER_PART = 25
 

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

@@ -2,22 +2,26 @@ 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'
+import type { WebCitation } from './tool-contracts'
 
 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 toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
 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>)
-    : {}
+  const record = toRecord(item)
+  if (!record) return {}
+  const metadata = toRecord(record.metadata)
+  return metadata ?? {}
 }
 
 function readSearchItemSnippet(record: Record<string, unknown>, metadata: Record<string, unknown>): string | undefined {
@@ -36,9 +40,9 @@ function readSearchItemSnippet(record: Record<string, unknown>, metadata: Record
 }
 
 function summarizeSearchItem(item: unknown): Record<string, string> | null {
-  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+  const record = toRecord(item)
+  if (!record) return null
 
-  const record = item as Record<string, unknown>
   const metadata = readMetadata(item)
   const url = extractUrlFromSearchItem(item)
 
@@ -79,9 +83,9 @@ function summarizeSearchItems(items: unknown[] | undefined): Record<string, unkn
 }
 
 function extractUrlFromSearchItem(item: unknown): string | undefined {
-  if (!item || typeof item !== 'object') return undefined
+  const record = toRecord(item)
+  if (!record) return undefined
 
-  const record = item as Record<string, unknown>
   if (typeof record.url === 'string' && record.url.trim().length > 0) {
     return record.url.trim()
   }
@@ -89,9 +93,8 @@ function extractUrlFromSearchItem(item: unknown): string | undefined {
     return record.imageUrl.trim()
   }
 
-  const metadata = record.metadata
-  if (metadata && typeof metadata === 'object') {
-    const metadataRecord = metadata as Record<string, unknown>
+  const metadataRecord = toRecord(record.metadata)
+  if (metadataRecord) {
     if (typeof metadataRecord.url === 'string' && metadataRecord.url.trim().length > 0) {
       return metadataRecord.url.trim()
     }
@@ -106,9 +109,9 @@ function extractUrlFromSearchItem(item: unknown): string | undefined {
   return undefined
 }
 
-function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): Citation[] {
+function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): WebCitation[] {
   const seen = new Set<string>()
-  const citations: Citation[] = []
+  const citations: WebCitation[] = []
   const retrievedAt = new Date().toISOString()
 
   const append = (items: unknown[] | undefined) => {

package/src/tools/{search-tools.ts → search.tool.ts}

@@ -22,7 +22,7 @@ export function createMemorySearchTool(
       const normalizedQuery = query.trim()
       const retrieval = await memoryService.searchAllMemoriesBatched({
         orgId: orgIdString,
-        agentName: isAgentName(agentName) ? (agentName as string) : undefined,
+        agentName: isAgentName(agentName) ? agentName : undefined,
         query: normalizedQuery,
         ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
         ...(typeof options?.allowMultiScopeRerank === 'boolean'

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

@@ -9,18 +9,21 @@ import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
 import { mergeInstructionSections } from '../runtime/instruction-sections'
 import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import type { LotaRuntimeTeamThinkToolsParams } 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> }> {
+async function buildTeamThinkAgentTools(
+  params: LotaRuntimeTeamThinkToolsParams,
+): Promise<{ tools: Record<string, unknown> }> {
   const builder = getRuntimeAdapters().workstream?.buildTeamThinkAgentTools
   if (!builder) {
     return { tools: {} }
   }
 
-  const result = await builder(params as never)
+  const result = await builder(params)
   return { tools: result.tools as Record<string, unknown> }
 }
 
@@ -79,13 +82,14 @@ export function createTeamThinkTool(params: {
         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]({
+      const agentId_ = typeof agentConfig.id === 'string' ? agentConfig.id : agentId
+      const maxSteps = typeof agentConfig.maxSteps === 'number' ? agentConfig.maxSteps : 10
+      const agent = createAgent[agentId_]({
         mode: 'fixedWorkstreamMode',
         tools,
         extraInstructions: agentConfig.extraInstructions,
         maxRetries: TEAM_THINK_AGENT_MAX_RETRIES,
-        stopWhen: [stepCountIs(agentConfig.maxSteps as number)],
+        stopWhen: [stepCountIs(maxSteps)],
       })
       const observer = {
         run: async <T>(fn: () => T | Promise<T>): Promise<T> => fn(),

package/src/tools/{tool-contract.ts → tool-contracts.ts}

@@ -7,7 +7,6 @@ export const MutatingApprovalSchema = {
   approvalMessageId: z.string().trim().min(1).max(200).optional(),
 } as const
 
-/** @lintignore */
 export const CitationSchema = z
   .object({
     source: z.string().trim().min(1),
@@ -17,5 +16,13 @@ export const CitationSchema = z
   })
   .strict()
 
-/** @lintignore */
 export type Citation = z.infer<typeof CitationSchema>
+
+export interface WebCitation {
+  title?: string
+  url?: string
+  snippet?: string
+  source?: string
+  sourceId?: string
+  retrievedAt?: string
+}

package/src/utils/async.ts

@@ -1,4 +1,4 @@
-import { getErrorMessage } from './error'
+import { getErrorMessage } from './errors'
 
 class TimeoutError extends Error {
   constructor(operation: string, ms: number) {

package/src/utils/errors.ts

@@ -1,3 +1,18 @@
+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)
+  }
+}
+
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value))
+}
+
 export class AppError extends Error {
   public readonly code: string
   public readonly statusCode: number

package/src/utils/hono-error-handler.ts

@@ -2,8 +2,7 @@ import type { ErrorHandler } from 'hono'
 import { HTTPException } from 'hono/http-exception'
 import { ZodError } from 'zod'
 
-import { getErrorMessage } from './error'
-import { AppError } from './errors'
+import { AppError, getErrorMessage } from './errors'
 
 type AppErrorLike = Pick<AppError, 'code' | 'message' | 'statusCode' | 'toResponse'> & { name?: string }