@lota-sdk/core 0.1.5 → 0.1.7

package/src/index.ts

@@ -1,6 +1,8 @@
 import type { CoreWorkstreamProfile } from './config/agent-defaults'
 import type { LotaWorkstreamConfig } from './config/workstream-defaults'
+import { ensureRecordId } from './db/record-id'
 import type { SurrealDBService } from './db/service'
+import { TABLES } from './db/tables'
 import type { startContextCompactionWorker } from './queues/context-compaction.queue'
 import type {
   scheduleRecurringConsolidation,
@@ -10,16 +12,22 @@ import type { startPostChatMemoryWorker } from './queues/post-chat-memory.queue'
 import type { startRecentActivityTitleRefinementWorker } from './queues/recent-activity-title-refinement.queue'
 import type { startRegularChatMemoryDigestWorker } from './queues/regular-chat-memory-digest.queue'
 import type { startSkillExtractionWorker } from './queues/skill-extraction.queue'
+import type { startWorkstreamTitleGenerationWorker } from './queues/workstream-title-generation.queue'
 import type { RedisConnectionManager } from './redis/connection'
 import type { isApprovalContinuationRequest } from './runtime/approval-continuation'
+import type { routeWorkstreamChatMessages } from './runtime/chat-request-routing'
 import type { LotaPlugin } from './runtime/plugin-types'
 import type { LotaRuntimeAdapters, LotaRuntimeTurnHooks } from './runtime/runtime-extensions'
 import type { attachmentService } from './services/attachment.service'
+import type { documentChunkService } from './services/document-chunk.service'
 import type { executionPlanService } from './services/execution-plan.service'
 import type { memoryService } from './services/memory.service'
 import type { verifyMutatingApproval } from './services/mutating-approval.service'
+import type { organizationMemberService } from './services/organization-member.service'
+import type { organizationService } from './services/organization.service'
 import type { recentActivityTitleService } from './services/recent-activity-title.service'
 import type { recentActivityService } from './services/recent-activity.service'
+import type { userService } from './services/user.service'
 import type { workstreamMessageService } from './services/workstream-message.service'
 import type { workstreamTitleService } from './services/workstream-title.service'
 import type {
@@ -39,11 +47,22 @@ interface LotaRuntimeBuiltInWorkers {
   startRecentActivityTitleRefinementWorker: typeof startRecentActivityTitleRefinementWorker
   startRegularChatMemoryDigestWorker: typeof startRegularChatMemoryDigestWorker
   startSkillExtractionWorker: typeof startSkillExtractionWorker
+  startWorkstreamTitleGenerationWorker: typeof startWorkstreamTitleGenerationWorker
   scheduleRecurringConsolidation: typeof scheduleRecurringConsolidation
 }
 
+type ArchiveSdkWorkstream = (
+  workstreamId: Parameters<typeof workstreamService.updateStatus>[0],
+  status?: 'archived',
+) => ReturnType<typeof workstreamService.updateStatus>
+
+type UnarchiveSdkWorkstream = (
+  workstreamId: Parameters<typeof workstreamService.updateStatus>[0],
+  status?: 'regular',
+) => ReturnType<typeof workstreamService.updateStatus>
+
 export interface LotaRuntimeConfig {
-  database: { url: string; namespace: string; database: string; username: string; password: string }
+  database: { url: string; namespace: string; username: string; password: string }
   redis: { url: string }
   aiGateway: { url: string; key: string; admin?: string; pass?: string; embeddingModel?: string }
   s3: {
@@ -56,8 +75,14 @@ export interface LotaRuntimeConfig {
   }
   firecrawl: { apiKey: string; apiBaseUrl?: string }
   logging?: { level?: 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'fatal' }
-  memory?: { searchK?: number }
+  memory?: { searchK?: number; embeddingCacheTtlSeconds?: number }
   workstreams?: LotaWorkstreamConfig
+  backgroundProcessing?: {
+    memoryExtractionFrequency?: number
+    skillExtractionFrequency?: number
+    memoryDigestFrequency?: number
+    memoryConsolidationFrequency?: number
+  }
 
   agents: {
     roster: readonly string[]
@@ -85,9 +110,13 @@ export interface LotaRuntime {
     redis: RedisConnectionManager
     closeRedisConnection: () => Promise<void>
     attachmentService: typeof attachmentService
+    documentChunkService: typeof documentChunkService
     generatedDocumentStorageService: typeof generatedDocumentStorageService
     memoryService: typeof memoryService
     verifyMutatingApproval: typeof verifyMutatingApproval
+    organizationService: typeof organizationService
+    organizationMemberService: typeof organizationMemberService
+    userService: typeof userService
     recentActivityService: typeof recentActivityService
     recentActivityTitleService: typeof recentActivityTitleService
     executionPlanService: typeof executionPlanService
@@ -99,6 +128,57 @@ export interface LotaRuntime {
     isApprovalContinuationRequest: typeof isApprovalContinuationRequest
     runWorkstreamTurnInBackground: typeof runWorkstreamTurnInBackground
   }
+  lota: {
+    organizations: {
+      create: typeof organizationService.createOrganization
+      upsert: typeof organizationService.upsertOrganization
+      get: typeof organizationService.getOrganization
+      list: typeof organizationService.listOrganizations
+      update: typeof organizationService.updateOrganization
+      delete: typeof organizationService.deleteOrganization
+    }
+    users: {
+      upsert: typeof userService.upsertUser
+      get: typeof userService.getUser
+      list: typeof userService.listUsers
+      update: typeof userService.updateUser
+      delete: typeof userService.deleteUser
+    }
+    memberships: {
+      add: typeof organizationMemberService.addMembership
+      listForOrganization: typeof organizationMemberService.listMembershipsForOrganization
+      listForUser: typeof organizationMemberService.listMembershipsForUser
+      remove: typeof organizationMemberService.removeMembership
+      isMember: typeof organizationMemberService.isMember
+    }
+    workstreams: {
+      create: typeof workstreamService.createWorkstream
+      list: typeof workstreamService.listWorkstreams
+      get: typeof workstreamService.getWorkstream
+      update: typeof workstreamService.updateTitle
+      archive: ArchiveSdkWorkstream
+      unarchive: UnarchiveSdkWorkstream
+      delete: typeof workstreamService.deleteWorkstream
+      stop: typeof workstreamService.stopActiveRun
+      listMessages: typeof workstreamMessageService.listMessageHistoryPage
+      getMessage: (params: { workstreamId: string; messageId: string }) => Promise<unknown>
+      sendMessage: (params: {
+        workstreamId: string
+        organizationId: string
+        userId: string
+        userName: string
+        messages: Parameters<typeof routeWorkstreamChatMessages>[0]
+      }) => Promise<Awaited<ReturnType<typeof createWorkstreamTurnStream>>>
+      continueApproval: (params: {
+        workstreamId: string
+        organizationId: string
+        userId: string
+        userName: string
+        messages: Parameters<typeof routeWorkstreamChatMessages>[0]
+      }) => Promise<Awaited<ReturnType<typeof createWorkstreamApprovalContinuationStream>>>
+      uploadAttachment: typeof attachmentService.uploadWorkstreamAttachment
+    }
+  }
   redis: {
     manager: RedisConnectionManager
     getConnection: () => ReturnType<RedisConnectionManager['getConnection']>
@@ -118,12 +198,30 @@ export interface LotaRuntime {
 export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<LotaRuntime> {
   const { lotaSdkEnvKeys, setEnv } = await import('./config/env-shapes')
   const { configureLogger } = await import('./config/logger')
+  const { publishDatabaseBootstrap } = await import('./db/startup')
+  const { computeSchemaFingerprint } = await import('./db/schema-fingerprint')
+  const { LOTA_SDK_DATABASE_NAME } = await import('./db/sdk-database')
   const { SurrealDBService: SurrealDBServiceClass, setDatabaseService } = await import('./db/service')
   const { createRedisConnectionManager } = await import('./redis/connection')
   const { setRedisConnectionManager } = await import('./redis/index')
   const { configureAgents, configureAgentFactory } = await import('./config/agent-defaults')
   const { configureWorkstreams } = await import('./config/workstream-defaults')
   const { configureRuntimeExtensions } = await import('./runtime/runtime-extensions')
+  const { routeWorkstreamChatMessages } = await import('./runtime/chat-request-routing')
+  const { configureBackgroundProcessing } = await import('./config/background-processing')
+  const { configureEmbeddingCache } = await import('./ai/embedding-cache')
+
+  // Resolve config defaults
+  const memory = {
+    searchK: config.memory?.searchK ?? 6,
+    embeddingCacheTtlSeconds: config.memory?.embeddingCacheTtlSeconds ?? 3600,
+  }
+  const backgroundProcessing = {
+    memoryExtractionFrequency: config.backgroundProcessing?.memoryExtractionFrequency ?? 3,
+    skillExtractionFrequency: config.backgroundProcessing?.skillExtractionFrequency ?? 5,
+    memoryDigestFrequency: config.backgroundProcessing?.memoryDigestFrequency ?? 1,
+    memoryConsolidationFrequency: config.backgroundProcessing?.memoryConsolidationFrequency ?? 10,
+  }
 
   setEnv({
     AI_GATEWAY_URL: config.aiGateway.url,
@@ -141,7 +239,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     ATTACHMENT_URL_EXPIRES_IN: config.s3.attachmentUrlExpiresIn ?? 1800,
     FIRECRAWL_API_KEY: config.firecrawl.apiKey,
     FIRECRAWL_API_BASE_URL: config.firecrawl.apiBaseUrl,
-    MEMORY_SEARCH_K: config.memory?.searchK ?? 6,
+    MEMORY_SEARCH_K: memory.searchK,
   })
 
   await configureLogger(config.logging?.level ?? 'info')
@@ -149,7 +247,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
   const db = new SurrealDBServiceClass({
     url: config.database.url,
     namespace: config.database.namespace,
-    database: config.database.database,
+    database: LOTA_SDK_DATABASE_NAME,
     username: config.database.username,
     password: config.database.password,
   })
@@ -157,6 +255,8 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
 
   const redisManager = createRedisConnectionManager({ url: config.redis.url })
   setRedisConnectionManager(redisManager)
+  configureEmbeddingCache(redisManager.getConnection(), memory.embeddingCacheTtlSeconds)
+  configureBackgroundProcessing(backgroundProcessing)
 
   configureAgents({
     roster: config.agents.roster,
@@ -177,11 +277,15 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
   }
 
   const { attachmentService } = await import('./services/attachment.service')
+  const { documentChunkService } = await import('./services/document-chunk.service')
   const { recentActivityService } = await import('./services/recent-activity.service')
   const { recentActivityTitleService } = await import('./services/recent-activity-title.service')
   const { executionPlanService } = await import('./services/execution-plan.service')
   const { memoryService } = await import('./services/memory.service')
   const { verifyMutatingApproval } = await import('./services/mutating-approval.service')
+  const { organizationMemberService } = await import('./services/organization-member.service')
+  const { organizationService } = await import('./services/organization.service')
+  const { userService } = await import('./services/user.service')
   const { workstreamMessageService } = await import('./services/workstream-message.service')
   const { workstreamService } = await import('./services/workstream.service')
   const { workstreamTitleService } = await import('./services/workstream-title.service')
@@ -199,6 +303,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
   const { startRecentActivityTitleRefinementWorker } = await import('./queues/recent-activity-title-refinement.queue')
   const { startRegularChatMemoryDigestWorker } = await import('./queues/regular-chat-memory-digest.queue')
   const { startSkillExtractionWorker } = await import('./queues/skill-extraction.queue')
+  const { startWorkstreamTitleGenerationWorker } = await import('./queues/workstream-title-generation.queue')
 
   configureRuntimeExtensions({
     adapters: config.runtimeAdapters,
@@ -209,11 +314,8 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
 
   const pluginRuntime = config.pluginRuntime ?? {}
   const pluginContributions = Object.values(pluginRuntime).map((plugin) => plugin.contributions)
-  const schemaFiles = [
-    ...getBuiltInSchemaFiles(),
-    ...pluginContributions.flatMap((plugin) => plugin.schemaFiles),
-    ...(config.extraSchemaFiles ?? []),
-  ]
+  const schemaFiles = [...getBuiltInSchemaFiles(), ...(config.extraSchemaFiles ?? [])]
+  const hostContributionSchemaFiles = pluginContributions.flatMap((plugin) => plugin.schemaFiles)
   const contributionEnvKeys = [...lotaSdkEnvKeys, ...pluginContributions.flatMap((plugin) => plugin.envKeys)]
   const connectPluginDatabases = createPluginDatabaseConnector(pluginRuntime)
   const builtInWorkers = {
@@ -223,9 +325,91 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     startRecentActivityTitleRefinementWorker,
     startRegularChatMemoryDigestWorker,
     startSkillExtractionWorker,
+    startWorkstreamTitleGenerationWorker,
     scheduleRecurringConsolidation,
   } satisfies LotaRuntimeBuiltInWorkers
 
+  const lota = {
+    organizations: {
+      create: organizationService.createOrganization.bind(organizationService),
+      upsert: organizationService.upsertOrganization.bind(organizationService),
+      get: organizationService.getOrganization.bind(organizationService),
+      list: organizationService.listOrganizations.bind(organizationService),
+      update: organizationService.updateOrganization.bind(organizationService),
+      delete: organizationService.deleteOrganization.bind(organizationService),
+    },
+    users: {
+      upsert: userService.upsertUser.bind(userService),
+      get: userService.getUser.bind(userService),
+      list: userService.listUsers.bind(userService),
+      update: userService.updateUser.bind(userService),
+      delete: userService.deleteUser.bind(userService),
+    },
+    memberships: {
+      add: organizationMemberService.addMembership.bind(organizationMemberService),
+      listForOrganization: organizationMemberService.listMembershipsForOrganization.bind(organizationMemberService),
+      listForUser: organizationMemberService.listMembershipsForUser.bind(organizationMemberService),
+      remove: organizationMemberService.removeMembership.bind(organizationMemberService),
+      isMember: organizationMemberService.isMember.bind(organizationMemberService),
+    },
+    workstreams: {
+      create: workstreamService.createWorkstream.bind(workstreamService),
+      list: workstreamService.listWorkstreams.bind(workstreamService),
+      get: workstreamService.getWorkstream.bind(workstreamService),
+      update: workstreamService.updateTitle.bind(workstreamService),
+      archive: async (workstreamId, status = 'archived') => await workstreamService.updateStatus(workstreamId, status),
+      unarchive: async (workstreamId, status = 'regular') => await workstreamService.updateStatus(workstreamId, status),
+      delete: workstreamService.deleteWorkstream.bind(workstreamService),
+      stop: workstreamService.stopActiveRun.bind(workstreamService),
+      listMessages: workstreamMessageService.listMessageHistoryPage.bind(workstreamMessageService),
+      getMessage: async ({ workstreamId, messageId }) => {
+        const messages = await workstreamMessageService.listMessages(ensureRecordId(workstreamId, TABLES.WORKSTREAM))
+        const message = messages.find((candidate) => candidate.id === messageId)
+        if (!message) {
+          throw new Error(`Workstream message not found: ${messageId}`)
+        }
+        return message
+      },
+      sendMessage: async ({ workstreamId, organizationId, userId, userName, messages }) => {
+        const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+        const workstream = await workstreamService.getWorkstream(workstreamRef)
+        const routed = routeWorkstreamChatMessages(messages)
+        if (routed.kind !== 'turn') {
+          throw new Error(routed.kind === 'invalid' ? routed.message : 'Expected a user turn payload.')
+        }
+
+        return await createWorkstreamTurnStream({
+          workstream,
+          workstreamRef,
+          orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+          userRef: ensureRecordId(userId, TABLES.USER),
+          userName,
+          inputMessage: routed.inputMessage,
+        })
+      },
+      continueApproval: async ({ workstreamId, organizationId, userId, userName, messages }) => {
+        const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+        const workstream = await workstreamService.getWorkstream(workstreamRef)
+        const routed = routeWorkstreamChatMessages(messages)
+        if (routed.kind !== 'approval-continuation') {
+          throw new Error(
+            routed.kind === 'invalid' ? routed.message : 'Expected approval continuation messages payload.',
+          )
+        }
+
+        return await createWorkstreamApprovalContinuationStream({
+          workstream,
+          workstreamRef,
+          orgRef: ensureRecordId(organizationId, TABLES.ORGANIZATION),
+          userRef: ensureRecordId(userId, TABLES.USER),
+          userName,
+          approvalMessages: routed.approvalMessages,
+        })
+      },
+      uploadAttachment: attachmentService.uploadWorkstreamAttachment.bind(attachmentService),
+    },
+  } satisfies LotaRuntime['lota']
+
   return {
     services: {
       database: db,
@@ -233,9 +417,13 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
       redis: redisManager,
       closeRedisConnection: async () => await redisManager.closeConnection(),
       attachmentService,
+      documentChunkService,
       generatedDocumentStorageService,
       memoryService,
       verifyMutatingApproval,
+      organizationService,
+      organizationMemberService,
+      userService,
       recentActivityService,
       recentActivityTitleService,
       executionPlanService,
@@ -247,6 +435,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
       isApprovalContinuationRequest,
       runWorkstreamTurnInBackground,
     },
+    lota,
     redis: {
       manager: redisManager,
       getConnection: () => redisManager.getConnection(),
@@ -255,7 +444,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     },
     workers: { ...builtInWorkers, ...config.extraWorkers },
     schemaFiles,
-    contributions: { envKeys: [...new Set(contributionEnvKeys)], schemaFiles },
+    contributions: { envKeys: [...new Set(contributionEnvKeys)], schemaFiles: hostContributionSchemaFiles },
     config,
     plugins: pluginRuntime,
     async connectPluginDatabases() {
@@ -263,6 +452,12 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     },
     async connect() {
       await db.connect()
+      const bunFiles = schemaFiles.map((schemaFile) =>
+        schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile),
+      )
+      await db.applySchemaAndMigrations(bunFiles)
+      const schemaFingerprint = await computeSchemaFingerprint(schemaFiles)
+      await publishDatabaseBootstrap({ databaseService: db, schemaFingerprint })
     },
     async disconnect() {
       await db.disconnect()
@@ -273,10 +468,12 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
 
 function getBuiltInSchemaFiles(): URL[] {
   return [
+    new URL('../infrastructure/schema/00_identity.surql', import.meta.url),
     new URL('../infrastructure/schema/00_workstream.surql', import.meta.url),
     new URL('../infrastructure/schema/01_memory.surql', import.meta.url),
     new URL('../infrastructure/schema/02_execution_plan.surql', import.meta.url),
     new URL('../infrastructure/schema/03_learned_skill.surql', import.meta.url),
+    new URL('../infrastructure/schema/05_recent_activity.surql', import.meta.url),
     new URL('../infrastructure/schema/04_runtime_bootstrap.surql', import.meta.url),
   ]
 }

package/src/queues/memory-consolidation.queue.ts

@@ -32,6 +32,12 @@ function getMemoryConsolidationQueue(): Queue<MemoryConsolidationJob> {
   return _memoryConsolidationQueue
 }
 
+export async function enqueueMemoryConsolidation(job: MemoryConsolidationJob = {}) {
+  await getMemoryConsolidationQueue().add('consolidate-turn', job, {
+    jobId: job.scopeId ? `consolidate-turn:${job.scopeId}` : undefined,
+  })
+}
+
 export async function scheduleRecurringConsolidation() {
   await getMemoryConsolidationQueue().add(
     'consolidate',

package/src/queues/workstream-title-generation.queue.ts

@@ -0,0 +1,69 @@
+import { Queue, Worker } from 'bullmq'
+import type { Job } from 'bullmq'
+
+import { serverLogger } from '../config/logger'
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { getRedisConnectionForBullMQ } from '../redis'
+import { workstreamTitleService } from '../services/workstream-title.service'
+import {
+  attachWorkerEvents,
+  createTracedWorkerProcessor,
+  createWorkerShutdown,
+  registerShutdownSignals,
+} from '../workers/worker-utils'
+import type { WorkerHandle } from '../workers/worker-utils'
+
+interface WorkstreamTitleGenerationJob {
+  workstreamId: string
+  sourceText: string
+}
+
+const WORKSTREAM_TITLE_GENERATION_QUEUE = 'workstream-title-generation'
+
+let _workstreamTitleGenerationQueue: Queue<WorkstreamTitleGenerationJob> | null = null
+function getWorkstreamTitleGenerationQueue(): Queue<WorkstreamTitleGenerationJob> {
+  if (!_workstreamTitleGenerationQueue) {
+    _workstreamTitleGenerationQueue = new Queue<WorkstreamTitleGenerationJob>(WORKSTREAM_TITLE_GENERATION_QUEUE, {
+      connection: getRedisConnectionForBullMQ(),
+      defaultJobOptions: {
+        removeOnComplete: 200,
+        removeOnFail: 200,
+        attempts: 2,
+        backoff: { type: 'exponential', delay: 2_000 },
+      },
+    })
+  }
+  return _workstreamTitleGenerationQueue
+}
+
+export async function enqueueWorkstreamTitleGeneration(job: WorkstreamTitleGenerationJob) {
+  return await getWorkstreamTitleGenerationQueue().add('generate-workstream-title', job, {
+    jobId: `workstream-title:${job.workstreamId}`,
+  })
+}
+
+async function processWorkstreamTitleGenerationJob(job: Job<WorkstreamTitleGenerationJob>): Promise<void> {
+  await databaseService.connect()
+  const workstreamRef = ensureRecordId(job.data.workstreamId)
+  await workstreamTitleService.generateAndPersistTitle(workstreamRef, job.data.sourceText)
+}
+
+export function startWorkstreamTitleGenerationWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
+  const { registerSignals = import.meta.main } = options
+  const worker = new Worker(
+    WORKSTREAM_TITLE_GENERATION_QUEUE,
+    createTracedWorkerProcessor(WORKSTREAM_TITLE_GENERATION_QUEUE, processWorkstreamTitleGenerationJob),
+    { connection: getRedisConnectionForBullMQ(), concurrency: 2, lockDuration: 60_000 },
+  )
+
+  attachWorkerEvents(worker, 'Workstream title generation', serverLogger)
+
+  const shutdown = createWorkerShutdown(worker, 'Workstream title generation', serverLogger)
+
+  if (registerSignals) {
+    registerShutdownSignals({ name: 'Workstream title generation', shutdown, logger: serverLogger })
+  }
+
+  return { worker, shutdown }
+}

package/src/runtime/agent-types.ts

@@ -1,22 +1,5 @@
-import type { Output, PrepareStepFunction, StopCondition, ToolLoopAgentOnFinishCallback, ToolSet } from 'ai'
-
-export type ChatMode = 'direct' | 'workstreamMode' | 'fixedWorkstreamMode'
-
-export interface CreateRoutedAgentOptions<TTools extends ToolSet = ToolSet> {
-  mode: ChatMode
-  tools: TTools
-  extraInstructions?: string
-  stopWhen?: StopCondition<TTools> | Array<StopCondition<TTools>>
-  prepareStep?: PrepareStepFunction<TTools>
-  maxRetries?: number
-  modelOverride?: { model: unknown; providerOptions?: Record<string, unknown> }
-  onFinish?: ToolLoopAgentOnFinishCallback<TTools>
-}
-
-export interface CreateHelperToolLoopAgentOptions {
-  instructions?: string
-  maxOutputTokens?: number
-  temperature?: number
-  output?: Output.Output
-  maxRetries?: number
-}
+export type {
+  ChatMode,
+  CreateHelperToolLoopAgentOptions,
+  CreateRoutedAgentOptions,
+} from '@lota-sdk/shared/runtime/agent-types'

package/src/runtime/helper-model.ts

@@ -48,6 +48,7 @@ export interface GenerateHelperStructuredParams<T> extends Omit<GenerateHelperTe
   tag: string
   schema: ZodSchema<T>
   textFallbackParser?: (text: string) => T | null
+  normalizeCandidate?: (candidate: unknown) => unknown
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -358,6 +359,14 @@ export function createHelperModelRuntime() {
         return parsed.data
       }
 
+      if (params.normalizeCandidate && isObject(result.output)) {
+        const normalized = params.normalizeCandidate(result.output)
+        const normalizedParsed = parseStructuredCandidate({ schema: params.schema, candidate: normalized })
+        if (normalizedParsed) {
+          return normalizedParsed.data
+        }
+      }
+
       if (typeof result.text === 'string' && result.text.trim().length > 0) {
         return parseStructuredTextWithFallbacks({
           schema: params.schema,
@@ -401,5 +410,3 @@ export function createHelperModelRuntime() {
 
   return { generateHelperText, generateHelperStructured }
 }
-
-export const llmHelperService = createHelperModelRuntime()

package/src/runtime/memory-digest-policy.ts

@@ -1,3 +1,5 @@
+import { getBackgroundProcessingConfig, shouldRunAtFrequency } from '../config/background-processing'
+
 export function shouldEnqueueOnboardingPostChatMemory(params: {
   onboardingActive: boolean
   userMessageText: string
@@ -9,6 +11,32 @@ export function shouldEnqueueOnboardingPostChatMemory(params: {
   return params.userMessageText.trim().length > 0 || params.hasAttachmentContext
 }
 
-export function shouldEnqueueRegularDigestForWorkstream(params: { onboardingActive: boolean }): boolean {
-  return !params.onboardingActive
+export function shouldEnqueueRegularDigestForWorkstream(params: {
+  onboardingActive: boolean
+  turnCount?: number
+}): boolean {
+  if (params.onboardingActive) return false
+  const { memoryDigestFrequency } = getBackgroundProcessingConfig()
+  if (typeof params.turnCount === 'number') {
+    return shouldRunAtFrequency(params.turnCount, memoryDigestFrequency)
+  }
+  return true
+}
+
+export function shouldEnqueueMemoryExtraction(params: { onboardingActive: boolean; turnCount?: number }): boolean {
+  if (params.onboardingActive) return true
+  const { memoryExtractionFrequency } = getBackgroundProcessingConfig()
+  if (typeof params.turnCount === 'number') {
+    return shouldRunAtFrequency(params.turnCount, memoryExtractionFrequency)
+  }
+  return true
+}
+
+export function shouldEnqueueMemoryConsolidation(params: { onboardingActive: boolean; turnCount?: number }): boolean {
+  if (params.onboardingActive) return false
+  const { memoryConsolidationFrequency } = getBackgroundProcessingConfig()
+  if (typeof params.turnCount === 'number') {
+    return shouldRunAtFrequency(params.turnCount, memoryConsolidationFrequency)
+  }
+  return false
 }

package/src/runtime/skill-extraction-policy.ts

@@ -1,3 +1,10 @@
-export function shouldEnqueueSkillExtraction(params: { onboardingActive: boolean }): boolean {
-  return !params.onboardingActive
+import { getBackgroundProcessingConfig, shouldRunAtFrequency } from '../config/background-processing'
+
+export function shouldEnqueueSkillExtraction(params: { onboardingActive: boolean; turnCount?: number }): boolean {
+  if (params.onboardingActive) return false
+  const { skillExtractionFrequency } = getBackgroundProcessingConfig()
+  if (typeof params.turnCount === 'number') {
+    return shouldRunAtFrequency(params.turnCount, skillExtractionFrequency)
+  }
+  return true
 }

package/src/services/memory.service.ts

@@ -8,10 +8,12 @@ import { isUniqueIndexConflict } from '../db/memory-store.helpers'
 import type {
   AddOptions,
   ExtractedFact,
+  MemoryListScalar,
   MemoryRecord,
   MemorySearchResult,
   MemoryType,
   Message,
+  RelationType,
 } from '../db/memory-types'
 import { withOrgMemoryLock } from '../redis/org-memory-lock'
 import { createHelperModelRuntime } from '../runtime/helper-model'
@@ -413,6 +415,19 @@ class MemoryService {
     return `Agent memory (${agentName}):\n${agentResult}\n\nGlobal org memory:\n${orgResult}`
   }
 
+  async listOrganizationMemoryRecords(params: {
+    orgId: string
+    limit?: number
+    memoryType?: MemoryType
+    metadataEquals?: Record<string, MemoryListScalar>
+    metadataNotEquals?: Record<string, MemoryListScalar>
+    sort?: 'createdAtAsc' | 'createdAtDesc'
+  }): Promise<MemoryRecord[]> {
+    const { orgId, ...listOptions } = params
+    const orgMemory = this.getOrgMemory(orgId)
+    return await orgMemory.list({ scopeId: scopeId(ORG_SCOPE_PREFIX, orgId), ...listOptions })
+  }
+
   async getTopMemories(params: { orgId: string; agentName?: string; limit?: number }): Promise<string | undefined> {
     const orgMemory = this.getOrgMemory(params.orgId)
     const orgScopeId = scopeId(ORG_SCOPE_PREFIX, params.orgId)
@@ -568,12 +583,14 @@ class MemoryService {
     memoryType,
     metadata,
     importance,
+    durability,
   }: {
     orgId: string
     content: string
     memoryType: MemoryType
     metadata?: Record<string, unknown>
     importance?: number
+    durability?: MemoryRecord['durability']
   }): Promise<string> {
     const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
     aiLogger.info`[MEMORY_DEBUG] createOrganizationMemory - orgId: "${orgId}", scopeId: "${orgScopeId}", content preview: "${content.slice(0, 50)}"`
@@ -583,6 +600,7 @@ class MemoryService {
         scopeId: orgScopeId,
         memoryType,
         importance: importance ?? 1,
+        durability,
         metadata: { orgId, ...metadata },
       })
     } catch (error) {
@@ -594,6 +612,23 @@ class MemoryService {
     }
   }
 
+  async addOrganizationMemoryRelation({
+    orgId,
+    fromMemoryId,
+    toMemoryId,
+    relationType,
+    confidence,
+  }: {
+    orgId: string
+    fromMemoryId: string
+    toMemoryId: string
+    relationType: RelationType
+    confidence?: number
+  }): Promise<void> {
+    const memory = this.getOrgMemory(orgId)
+    await memory.addRelation(fromMemoryId, toMemoryId, relationType, confidence)
+  }
+
   async createAgentMemory({
     orgId,
     agentName,