@lota-sdk/core 0.4.8 → 0.4.10

package/src/runtime/{memory-block.ts → memory/memory-block.ts}

@@ -1,31 +1,34 @@
+import { Effect, Schema } from 'effect'
 import { z } from 'zod'
 
-import { agentDisplayNames, agentShortDisplayNames, resolveAgentNameAlias } from '../config/agent-defaults'
-import { compactWhitespace } from '../utils/string'
+import { nowDate } from '../../utils/date-time'
+import { compactWhitespace } from '../../utils/string'
+
+export class MemoryBlockCompactError extends Schema.TaggedErrorClass<MemoryBlockCompactError>()(
+  'MemoryBlockCompactError',
+  { message: Schema.String, cause: Schema.Defect },
+) {}
 
 function escapeRegex(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
 function normalizeMemoryBlockRole(role: string): string {
-  const canonicalRole = resolveAgentNameAlias(role)
-  if (canonicalRole) return canonicalRole
   return role.trim().toLowerCase()
 }
 
+function toLabelAlias(role: string): string {
+  const trimmed = role.trim()
+  if (!trimmed) return ''
+  return trimmed.length === 1 ? trimmed.toUpperCase() : `${trimmed[0].toUpperCase()}${trimmed.slice(1).toLowerCase()}`
+}
+
 function getMemoryBlockRoleAliases(role: string): string[] {
   const normalizedRole = role.trim()
   if (!normalizedRole) return []
-
-  const canonicalRole = resolveAgentNameAlias(normalizedRole)
-  if (!canonicalRole) return [normalizedRole]
-
-  return [
-    normalizedRole,
-    canonicalRole,
-    agentDisplayNames[canonicalRole],
-    agentShortDisplayNames[canonicalRole],
-  ].filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+  return [normalizedRole, normalizedRole.toLowerCase(), toLabelAlias(normalizedRole)].filter(
+    (value): value is string => typeof value === 'string' && value.trim().length > 0,
+  )
 }
 
 function createLabelPrefixRegex(labelRoles: readonly string[]): RegExp | null {
@@ -59,7 +62,10 @@ export interface CompactMemoryBlockEntriesParams {
   entries: MemoryBlockEntry[]
   triggerEntries: number
   chunkEntries: number
-  compact: (params: { previousSummary: string; newEntriesText: string }) => Promise<string>
+  compact: (params: {
+    previousSummary: string
+    newEntriesText: string
+  }) => PromiseLike<string> | Effect.Effect<string, MemoryBlockCompactError>
 }
 
 export interface CompactMemoryBlockEntriesResult {
@@ -102,29 +108,37 @@ function toMemoryBlockEntriesSource(entries: Array<{ role: string; content: stri
   return entries.map((entry) => `${entry.role}: ${entry.content}`).join('\n')
 }
 
-export async function compactMemoryBlockEntries(
+export function compactMemoryBlockEntries(
   params: CompactMemoryBlockEntriesParams,
-): Promise<CompactMemoryBlockEntriesResult> {
-  let summary = typeof params.previousSummary === 'string' ? params.previousSummary.trim() : ''
-  let entries = [...params.entries]
-  let compacted = false
-
-  while (entries.length >= params.triggerEntries) {
-    const chunk = entries.slice(0, params.chunkEntries)
-    const nextSummary = (
-      await params.compact({ previousSummary: summary, newEntriesText: toMemoryBlockEntriesSource(chunk) })
-    ).trim()
-
-    if (!nextSummary) {
-      break
+): Effect.Effect<CompactMemoryBlockEntriesResult, MemoryBlockCompactError> {
+  return Effect.gen(function* () {
+    let summary = typeof params.previousSummary === 'string' ? params.previousSummary.trim() : ''
+    let entries = [...params.entries]
+    let compacted = false
+
+    while (entries.length >= params.triggerEntries) {
+      const chunk = entries.slice(0, params.chunkEntries)
+      const compactParams = { previousSummary: summary, newEntriesText: toMemoryBlockEntriesSource(chunk) }
+      const value = params.compact(compactParams)
+      const raw = yield* Effect.isEffect(value)
+        ? value
+        : Effect.tryPromise({
+            try: () => Promise.resolve(value),
+            catch: (cause) => new MemoryBlockCompactError({ message: 'compact callback failed', cause }),
+          })
+      const nextSummary = raw.trim()
+
+      if (!nextSummary) {
+        break
+      }
+
+      summary = nextSummary
+      entries = entries.slice(params.chunkEntries)
+      compacted = true
     }
 
-    summary = nextSummary
-    entries = entries.slice(params.chunkEntries)
-    compacted = true
-  }
-
-  return { compacted, summary, entries }
+    return { compacted, summary, entries }
+  })
 }
 
 export function prepareMemoryBlockAppend(params: PrepareMemoryBlockAppendParams): PrepareMemoryBlockAppendResult {
@@ -158,7 +172,7 @@ export interface CreateMemoryBlockRuntimeOptions {
 export function createMemoryBlockRuntime(options: CreateMemoryBlockRuntimeOptions = {}): MemoryBlockRuntime {
   const labelPrefixRegex = createLabelPrefixRegex(options.labelRoles ?? [])
   const memoryBlockMaxChars = options.maxChars ?? 400
-  const now = options.now ?? (() => new Date())
+  const now = options.now ?? nowDate
 
   const normalizeMemoryBlockEntry = (entry: string): string => {
     const normalizedLines = entry

package/src/runtime/{memory-digest-policy.ts → memory/memory-digest-policy.ts}

@@ -1,4 +1,4 @@
-import { getBackgroundProcessingConfig, shouldRunAtFrequency } from '../config/background-processing'
+import { getBackgroundProcessingConfig, shouldRunAtFrequency } from '../../config/background-processing'
 
 export function shouldEnqueueOnboardingPostChatMemory(params: {
   onboardingActive: boolean

package/src/runtime/{memory-pipeline.ts → memory/memory-pipeline.ts}

@@ -1,4 +1,6 @@
-import { clampImportance, compactWhitespace } from '../utils/string'
+import { Match } from 'effect'
+
+import { clampImportance, compactWhitespace } from '../../utils/string'
 
 const SCORE_WEIGHTS = {
   durability: { core: 0.35, standard: 0.2, weak: 0.05 },
@@ -123,20 +125,17 @@ function scoreFact<T extends MemoryFactInput>(fact: T): number {
   const durability = fact.durability ?? 'standard'
   const type = fact.type ?? 'fact'
 
-  const durabilityWeight =
-    durability === 'core'
-      ? SCORE_WEIGHTS.durability.core
-      : durability === 'standard'
-        ? SCORE_WEIGHTS.durability.standard
-        : SCORE_WEIGHTS.durability.weak
-  const typeWeight =
-    type === 'decision'
-      ? SCORE_WEIGHTS.type.decision
-      : type === 'fact'
-        ? SCORE_WEIGHTS.type.fact
-        : type === 'preference'
-          ? SCORE_WEIGHTS.type.preference
-          : SCORE_WEIGHTS.type.default
+  const durabilityWeight = Match.value(durability).pipe(
+    Match.when('core', () => SCORE_WEIGHTS.durability.core),
+    Match.when('standard', () => SCORE_WEIGHTS.durability.standard),
+    Match.orElse(() => SCORE_WEIGHTS.durability.weak),
+  )
+  const typeWeight = Match.value(type).pipe(
+    Match.when('decision', () => SCORE_WEIGHTS.type.decision),
+    Match.when('fact', () => SCORE_WEIGHTS.type.fact),
+    Match.when('preference', () => SCORE_WEIGHTS.type.preference),
+    Match.orElse(() => SCORE_WEIGHTS.type.default),
+  )
   const lengthWeight =
     Math.min(fact.content.length, SCORE_WEIGHTS.maxContentLength) / SCORE_WEIGHTS.maxContentLength / 10
 
@@ -340,61 +339,49 @@ export function compileMemoryUpdatesFromDelta(params: {
       deleteSet.add(invalidateId)
     }
 
-    if (item.classification === 'duplicate') {
-      const targetId = item.targetMemoryIds[0]
-      if (targetId) {
-        updates.push({ id: targetId, text: existingById.get(targetId) ?? item.fact, event: 'NONE' })
-      } else {
-        updates.push({ id: `noop_${item.index}`, text: item.fact, event: 'NONE' })
-      }
-      continue
-    }
-
-    if (item.classification === 'enriches') {
-      const targetId = item.targetMemoryIds[0]
-      if (targetId) {
-        const relations = buildRelations(item, 'new').filter((relation) => relation.memoryId !== targetId)
-        updates.push({
-          id: targetId,
-          text: item.fact,
-          event: 'UPDATE',
-          oldMemory: existingById.get(targetId),
-          ...(relations.length > 0 ? { relatesTo: relations } : {}),
-        })
-        continue
-      }
+    const nextUpdates = Match.value(item.classification).pipe(
+      Match.when('duplicate', (): MemoryUpdateItemLike[] => {
+        const targetId = item.targetMemoryIds[0]
+        if (targetId) {
+          return [{ id: targetId, text: existingById.get(targetId) ?? item.fact, event: 'NONE' }]
+        }
+        return [{ id: `noop_${item.index}`, text: item.fact, event: 'NONE' }]
+      }),
+      Match.when('enriches', (): MemoryUpdateItemLike[] => {
+        const targetId = item.targetMemoryIds[0]
+        if (targetId) {
+          const relations = buildRelations(item, 'new').filter((relation) => relation.memoryId !== targetId)
+          return [
+            {
+              id: targetId,
+              text: item.fact,
+              event: 'UPDATE',
+              oldMemory: existingById.get(targetId),
+              ...(relations.length > 0 ? { relatesTo: relations } : {}),
+            },
+          ]
+        }
 
-      const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
-      const relations = buildRelations(item, 'new')
-      updates.push({
-        id: addId,
-        text: item.fact,
-        event: 'ADD',
-        ...(relations.length > 0 ? { relatesTo: relations } : {}),
-      })
-      continue
-    }
+        const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+        const relations = buildRelations(item, 'new')
+        return [{ id: addId, text: item.fact, event: 'ADD', ...(relations.length > 0 ? { relatesTo: relations } : {}) }]
+      }),
+      Match.whenOr('supersedes', 'contradicts', (classification): MemoryUpdateItemLike[] => {
+        const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+        const relations = buildRelations(item, classification)
+        return [{ id: addId, text: item.fact, event: 'ADD', ...(relations.length > 0 ? { relatesTo: relations } : {}) }]
+      }),
+      Match.when('new', (): MemoryUpdateItemLike[] => {
+        const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+        const relations = buildRelations(item, 'new')
+        return [{ id: addId, text: item.fact, event: 'ADD', ...(relations.length > 0 ? { relatesTo: relations } : {}) }]
+      }),
+      Match.exhaustive,
+    )
 
-    if (item.classification === 'supersedes' || item.classification === 'contradicts') {
-      const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
-      const relations = buildRelations(item, item.classification)
-      updates.push({
-        id: addId,
-        text: item.fact,
-        event: 'ADD',
-        ...(relations.length > 0 ? { relatesTo: relations } : {}),
-      })
-      continue
+    for (const update of nextUpdates) {
+      updates.push(update)
     }
-
-    const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
-    const relations = buildRelations(item, 'new')
-    updates.push({
-      id: addId,
-      text: item.fact,
-      event: 'ADD',
-      ...(relations.length > 0 ? { relatesTo: relations } : {}),
-    })
   }
 
   const preservedRelationTargetIds = new Set<string>()

package/src/runtime/{memory-prompts-fact.ts → memory/memory-prompts-fact.ts}

@@ -1,4 +1,4 @@
-import { formatUtcPromptDate } from '../utils/date-time'
+import { formatUtcPromptDate, nowDate } from '../../utils/date-time'
 
 export function getFactRetrievalMessages(
   parsedMessages: string,
@@ -56,7 +56,7 @@ Hard rules:
 - Prefer returning fewer items. If uncertain, return an empty list.
 - Max ${maxFacts} facts.
 
-Today's date is ${formatUtcPromptDate(new Date())}.
+Today's date is ${formatUtcPromptDate(nowDate())}.
 ${baseInstructions}`
 
   const userPrompt = `Conversation:\n${parsedMessages}`

package/src/runtime/memory/memory-scope.ts

@@ -0,0 +1,53 @@
+import { Effect, Schema } from 'effect'
+
+export const ORG_SCOPE_PREFIX = 'org'
+
+const SCOPE_ID_MAX_LENGTH = 255
+const SCOPE_PREFIX_REGEX = /^[a-z][a-z0-9_]*$/
+
+export class MemoryScopeError extends Schema.TaggedErrorClass<MemoryScopeError>()('MemoryScopeError', {
+  message: Schema.String,
+}) {}
+
+function stripRecordPrefix(id: string): Effect.Effect<string, MemoryScopeError> {
+  if (typeof id !== 'string' || id.length === 0) {
+    return Effect.fail(new MemoryScopeError({ message: 'id must be a non-empty string' }))
+  }
+  const [, ...rest] = id.split(':')
+  return Effect.succeed(rest.length > 0 ? rest.join(':') : id)
+}
+
+export function scopeId(prefix: string, id: string): Effect.Effect<string, MemoryScopeError> {
+  return Effect.gen(function* () {
+    if (typeof prefix !== 'string' || prefix.length === 0) {
+      return yield* new MemoryScopeError({ message: 'prefix must be a non-empty string' })
+    }
+    if (!SCOPE_PREFIX_REGEX.test(prefix)) {
+      return yield* new MemoryScopeError({ message: `Invalid scope prefix: ${prefix}` })
+    }
+
+    const stripped = yield* stripRecordPrefix(id)
+    const scoped = `${prefix}:${stripped}`
+    if (scoped.length > SCOPE_ID_MAX_LENGTH) {
+      return yield* new MemoryScopeError({ message: 'scopeId exceeds maximum length' })
+    }
+
+    return scoped
+  })
+}
+
+export function agentScopeId(orgId: string, agentName: string): Effect.Effect<string, MemoryScopeError> {
+  return Effect.gen(function* () {
+    if (typeof agentName !== 'string' || agentName.trim().length === 0) {
+      return yield* new MemoryScopeError({ message: 'agentName must be a non-empty string' })
+    }
+    const strippedOrgId = yield* stripRecordPrefix(orgId)
+    const scoped = `agent:${strippedOrgId}:${agentName.trim()}`
+
+    if (scoped.length > SCOPE_ID_MAX_LENGTH) {
+      return yield* new MemoryScopeError({ message: 'scopeId exceeds maximum length' })
+    }
+
+    return scoped
+  })
+}

package/src/runtime/plugin-resolution.ts

@@ -1,36 +1,135 @@
-import { pluginRuntime } from '../config/agent-defaults'
+import { Schema, Effect } from 'effect'
+
+import { getPluginRuntime } from '../config/agent-defaults'
+import type { RecordIdRef } from '../db/record-id'
 import type { LotaRuntimeIndexedRepositoriesContext } from './runtime-extensions'
 import { getRuntimeAdapters } from './runtime-extensions'
 
-export function getPluginService(path: string[]): ((...args: unknown[]) => unknown) | undefined {
-  let current: unknown = pluginRuntime
-  let owner: unknown = undefined
-  for (const key of path) {
-    if (current === null || current === undefined || typeof current !== 'object') return undefined
-    owner = current
-    current = (current as Record<string, unknown>)[key]
-  }
-  if (typeof current !== 'function') {
-    return undefined
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+class PluginResolutionError extends Schema.TaggedErrorClass<PluginResolutionError>()('PluginResolutionError', {
+  stage: Schema.Literals([
+    'configuration',
+    'linear-installation',
+    'github-installation',
+    'indexed-repositories-context',
+  ]),
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function toPluginResolutionError(stage: PluginResolutionError['stage'], cause: unknown): PluginResolutionError {
+  return new PluginResolutionError({ stage, message: cause instanceof Error ? cause.message : String(cause), cause })
+}
+
+function readFunctionEffect(
+  value: unknown,
+  errorMessage: string,
+): Effect.Effect<(...args: unknown[]) => PromiseLike<unknown>, PluginResolutionError> {
+  if (typeof value !== 'function') {
+    return Effect.fail(new PluginResolutionError({ stage: 'configuration', message: errorMessage, cause: undefined }))
   }
 
-  return owner && typeof owner === 'object'
-    ? (current as (...args: unknown[]) => unknown).bind(owner)
-    : (current as (...args: unknown[]) => unknown)
+  return Effect.succeed(value as (...args: unknown[]) => PromiseLike<unknown>)
+}
+
+function configError(message: string): PluginResolutionError {
+  return new PluginResolutionError({ stage: 'configuration', message, cause: undefined })
+}
+
+function requireRecord(value: unknown, message: string): Effect.Effect<Record<string, unknown>, PluginResolutionError> {
+  return isRecord(value) ? Effect.succeed(value) : Effect.fail(configError(message))
+}
+
+function resolvePluginServiceEffect(
+  pluginName: string,
+  serviceName: string,
+  methodName: string,
+): Effect.Effect<(...args: unknown[]) => PromiseLike<unknown>, PluginResolutionError> {
+  return Effect.fromNullishOr(getPluginRuntime()).pipe(
+    Effect.mapError(() => configError(`Plugin runtime is not configured. Missing "${pluginName}" integration.`)),
+    Effect.flatMap((pluginRuntime) =>
+      requireRecord(pluginRuntime[pluginName], `Plugin "${pluginName}" is not configured in the current runtime.`),
+    ),
+    Effect.flatMap((plugin) =>
+      requireRecord(plugin.services, `Plugin "${pluginName}" does not expose a services registry.`),
+    ),
+    Effect.flatMap((services) =>
+      requireRecord(services[serviceName], `Plugin "${pluginName}" service "${serviceName}" is not configured.`).pipe(
+        Effect.flatMap((service) =>
+          readFunctionEffect(
+            service[methodName],
+            `Plugin "${pluginName}" service "${serviceName}" is missing method "${methodName}".`,
+          ).pipe(
+            Effect.map(
+              (method) =>
+                (...args: unknown[]) =>
+                  Reflect.apply(method, service, args),
+            ),
+          ),
+        ),
+      ),
+    ),
+  )
+}
+
+function tryResolvePluginServiceEffect(
+  pluginName: string,
+  serviceName: string,
+  methodName: string,
+): Effect.Effect<((...args: unknown[]) => PromiseLike<unknown>) | void, never, never> {
+  return Effect.catch(resolvePluginServiceEffect(pluginName, serviceName, methodName), () => Effect.void)
+}
+
+export function getLinearInstallationByOrgId(organizationId: RecordIdRef): Promise<unknown> {
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const fn = yield* tryResolvePluginServiceEffect('linear', 'linearService', 'getInstallationByOrgId')
+      if (!fn) return null
+      return yield* Effect.tryPromise({
+        try: () => fn(organizationId),
+        catch: (cause) => toPluginResolutionError('linear-installation', cause),
+      })
+    }),
+  )
+}
+
+export function getGithubInstallationForOrganization(organizationId: string): Promise<unknown> {
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const fn = yield* tryResolvePluginServiceEffect('github', 'githubService', 'getInstallationForOrganization')
+      if (!fn) return null
+      return yield* Effect.tryPromise({
+        try: () => fn(organizationId),
+        catch: (cause) => toPluginResolutionError('github-installation', cause),
+      })
+    }),
+  )
+}
+
+const EMPTY_INDEXED_REPO_CONTEXT: LotaRuntimeIndexedRepositoriesContext = {
+  provideRepoTool: false,
+  defaultSectionsByAgent: {},
+  context: '',
 }
 
-export async function buildIndexedRepositoriesContext(
+export function buildIndexedRepositoriesContext(
   organizationId: string,
 ): Promise<LotaRuntimeIndexedRepositoriesContext> {
   const buildContext = getRuntimeAdapters().buildIndexedRepositoriesContext
-  if (!buildContext) {
-    return { provideRepoTool: false, defaultSectionsByAgent: {}, context: '' }
-  }
-
-  const result = await buildContext(organizationId)
-  return {
-    provideRepoTool: result.provideRepoTool,
-    defaultSectionsByAgent: result.defaultSectionsByAgent,
-    context: result.context ?? '',
-  }
+  if (!buildContext) return Promise.resolve(EMPTY_INDEXED_REPO_CONTEXT)
+  return Effect.runPromise(
+    Effect.tryPromise({
+      try: () => buildContext(organizationId),
+      catch: (cause) => toPluginResolutionError('indexed-repositories-context', cause),
+    }).pipe(
+      Effect.map((result) => ({
+        provideRepoTool: result.provideRepoTool,
+        defaultSectionsByAgent: result.defaultSectionsByAgent,
+        context: result.context ?? '',
+      })),
+    ),
+  )
 }

package/src/runtime/plugin-types.ts

@@ -33,7 +33,15 @@ export interface SystemNodeExecutor {
   executeNode(params: PluginNodeExecutionParams): Promise<PlanNodeResult>
 }
 
-export interface LotaPlugin<TServices = Record<string, unknown>, TTools = Record<string, unknown>> {
+export interface PluginLifecycleServices {
+  connectDatabase?(): Promise<void>
+  disconnectDatabase?(): Promise<void>
+}
+
+export interface LotaPlugin<
+  TServices extends Record<string, unknown> = Record<string, unknown>,
+  TTools = Record<string, unknown>,
+> {
   services: TServices
   nodeExecutor?: PluginNodeExecutor
   tools?: TTools