@lota-sdk/core 0.1.14 → 0.1.16

package/src/services/global-orchestrator.service.ts

@@ -0,0 +1,148 @@
+import type { ConvergenceState, PlanFailureClass } from '@lota-sdk/shared'
+
+import { serverLogger } from '../config/logger'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+
+function classifyDispatchFailure(ownerType: string, error: unknown): PlanFailureClass {
+  const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+  if (errorMessage.includes('timeout')) return 'timeout_exceeded'
+  if (ownerType === 'plugin' || ownerType === 'system') return 'external_system_unavailable'
+  return 'non_recoverable_logic_error'
+}
+
+function formatDispatchError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+const STABLE_RUN_STATUSES = new Set(['awaiting-human', 'blocked', 'failed', 'completed', 'aborted'])
+
+class GlobalOrchestratorService {
+  detectConvergence(params: {
+    totalNodes: number
+    completedNodes: number
+    failedNodes: number
+    previousCompletedNodes?: number
+    previousFailedNodes?: number
+  }): ConvergenceState {
+    const completionRatio = params.totalNodes > 0 ? params.completedNodes / params.totalNodes : 0
+    const failureRatio = params.totalNodes > 0 ? params.failedNodes / params.totalNodes : 0
+
+    if (params.previousCompletedNodes !== undefined) {
+      const completionVelocity = params.completedNodes - params.previousCompletedNodes
+      const failureVelocity = params.failedNodes - (params.previousFailedNodes ?? 0)
+
+      if (completionVelocity > 0 && failureVelocity === 0) return 'converging'
+      if (completionVelocity === 0 && failureVelocity === 0) return 'stalled'
+      if (failureVelocity > 0) return 'diverging'
+    }
+
+    if (completionRatio > 0.5 && failureRatio === 0) return 'converging'
+    if (failureRatio > 0.3) return 'diverging'
+    return 'progressing'
+  }
+
+  decideRerouteAction(params: {
+    failedNodeId: string
+    retryCount: number
+    maxRetries: number
+    convergenceState: ConvergenceState
+  }): 'retry' | 'skip' | 'abort' {
+    if (params.retryCount < params.maxRetries) return 'retry'
+    if (params.convergenceState === 'converging') return 'skip'
+    if (params.convergenceState === 'diverging') return 'abort'
+    return 'skip'
+  }
+
+  async routeGraphFull(params: { workstreamId: string; runId: string }): Promise<void> {
+    const MAX_ROUNDS = 32
+    const STRUCTURAL_TYPES = new Set(['switch', 'join', 'deliberation-fork'])
+
+    // Dynamic imports to avoid circular dependencies
+    const { planRunService } = await import('./plan-run.service')
+    const { ownershipDispatcherService } = await import('./ownership-dispatcher.service')
+    const { planExecutorService } = await import('./plan-executor.service')
+
+    let round = 0
+    for (; round < MAX_ROUNDS; round++) {
+      const run = await planRunService.getRunById(params.runId)
+      if (STABLE_RUN_STATUSES.has(run.status)) break
+
+      const spec = await planRunService.getPlanSpecById(run.planSpecId)
+      const nodeSpecs = await planRunService.listNodeSpecs(spec.id)
+      const nodeRuns = await planRunService.listNodeRuns(run.id)
+
+      // Find ready action nodes (not structural, not human — those are handled by syncRunGraph)
+      const readyNodes = nodeRuns.filter((nr) => {
+        if (nr.status !== 'ready') return false
+        const ns = nodeSpecs.find((s) => s.nodeId === nr.nodeId)
+        return ns && ns.owner.executorType !== 'user' && !STRUCTURAL_TYPES.has(ns.type)
+      })
+      if (readyNodes.length === 0) break
+
+      // Transition all ready nodes to 'running' BEFORE dispatching
+      for (const nodeRun of readyNodes) {
+        await planExecutorService.transitionNodeToRunning({ runId: params.runId, nodeId: nodeRun.nodeId })
+      }
+
+      // Re-fetch run after transitions for accurate state in dispatch context
+      const updatedRun = await planRunService.getRunById(params.runId)
+
+      // Dispatch all in parallel with LINEAR mode override (prevents recursion)
+      const results = await Promise.allSettled(
+        readyNodes.map(async (nodeRun) => {
+          const nodeSpecRecord = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
+          if (!nodeSpecRecord) {
+            throw new Error(`Node spec not found for node "${nodeRun.nodeId}".`)
+          }
+          // Re-fetch the node run to get the updated 'running' state with resolvedInput
+          const updatedNodeRun = await planRunService.getNodeRunByNodeId(updatedRun.id, nodeRun.nodeId)
+          const result = await ownershipDispatcherService.dispatchReadyNode({
+            run: updatedRun,
+            nodeSpecRecord,
+            nodeRun: updatedNodeRun,
+            spec,
+            executionModeOverride: 'linear',
+          })
+          return { nodeId: nodeRun.nodeId, ownerRef: nodeSpecRecord.owner.ref, result }
+        }),
+      )
+
+      const workstreamId = recordIdToString(updatedRun.workstreamId, TABLES.WORKSTREAM)
+      const runId = recordIdToString(updatedRun.id, TABLES.PLAN_RUN)
+
+      // Submit results sequentially (each triggers syncRunGraph internally)
+      for (let i = 0; i < results.length; i++) {
+        const settled = results[i]
+        const nodeRun = readyNodes[i]
+        const nodeSpecRecord = nodeSpecs.find((ns) => ns.nodeId === nodeRun.nodeId)
+
+        if (settled.status === 'fulfilled') {
+          await planExecutorService.submitNodeResult({
+            workstreamId,
+            runId,
+            nodeId: settled.value.nodeId,
+            emittedBy: settled.value.ownerRef,
+            result: settled.value.result,
+          })
+        } else {
+          serverLogger.warn`routeGraphFull: dispatch failed for node "${nodeRun.nodeId}": ${settled.reason}`
+          await planExecutorService.blockNodeOnDispatchFailure({
+            workstreamId,
+            runId,
+            nodeId: nodeRun.nodeId,
+            emittedBy: nodeSpecRecord?.owner.ref ?? 'unknown',
+            message: formatDispatchError(settled.reason),
+            failureClass: classifyDispatchFailure(nodeSpecRecord?.owner.executorType ?? 'agent', settled.reason),
+          })
+        }
+      }
+    }
+
+    if (round === MAX_ROUNDS - 1) {
+      serverLogger.warn`graph-full execution reached max rounds (${MAX_ROUNDS}) for run ${params.runId} — possible non-converging graph`
+    }
+  }
+}
+
+export const globalOrchestratorService = new GlobalOrchestratorService()

package/src/services/index.ts

@@ -1,14 +1,40 @@
+export * from './adaptive-playbook.service'
+export * from './agent-executor.service'
+export * from './artifact-provenance.service'
 export * from './attachment.service'
+export * from './context-enrichment.service'
+export * from './coordination-registry.service'
 export * from './document-chunk.service'
+export * from './domain-agent-executor.service'
 export * from './execution-plan.service'
+export * from './institutional-memory.service'
+export * from './feedback-loop.service'
+export * from './global-orchestrator.service'
 export * from './memory.service'
+export * from './node-workspace.service'
+export * from './notification.service'
+export * from './ownership-dispatcher.service'
 export * from './organization-member.service'
 export * from './organization.service'
+export * from './plan-coordination.service'
+export * from './plan-cycle.service'
+export * from './plan-deadline.service'
+export * from './plan-workspace.service'
 export * from './plan-run.service'
+export * from './plan-scheduler.service'
+export * from './plan-template.service'
+export * from './playbook-registry.service'
+export * from './quality-metrics.service'
+export * from './monitoring-window.service'
+export * from './plugin-executor.service'
 export * from './recent-activity-title.service'
 export * from './recent-activity.service'
+export * from './skill-resolver.service'
+export * from './system-executor.service'
 export * from './user.service'
 export * from './workstream-message.service'
 export * from './workstream-title.service'
 export * from './workstream-turn'
+export * from './workstream-plan-registry.service'
 export * from './workstream.service'
+export * from './write-intent-validator.service'

package/src/services/institutional-memory.service.ts

@@ -0,0 +1,145 @@
+import type { InstitutionalMemory, InstitutionalMemoryType } from '@lota-sdk/shared'
+import { InstitutionalMemorySchema } from '@lota-sdk/shared'
+import { BoundQuery } from 'surrealdb'
+
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+
+class InstitutionalMemoryService {
+  async extractPatterns(params: { organizationId: string; runId: string }): Promise<InstitutionalMemory[]> {
+    const { planRunService } = await import('./plan-run.service')
+
+    const run = await planRunService.getRunById(params.runId)
+    const nodeRuns = await planRunService.listNodeRuns(run.id)
+    const nodeSpecs = await planRunService.listNodeSpecs(run.planSpecId)
+    const nodeSpecsByNodeId = new Map(nodeSpecs.map((n) => [n.nodeId, n]))
+
+    const patterns: InstitutionalMemory[] = []
+    const orgRef = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
+    const ownerRef = (nodeId: string): string => nodeSpecsByNodeId.get(nodeId)?.owner.ref ?? 'unknown'
+
+    const completedNodes = nodeRuns.filter((nr) => nr.status === 'completed' && nr.startedAt && nr.completedAt)
+    if (completedNodes.length > 0) {
+      const timings = completedNodes.map((nr) => ({
+        nodeId: nr.nodeId,
+        owner: ownerRef(nr.nodeId),
+        durationMs: new Date(nr.completedAt ?? 0).getTime() - new Date(nr.startedAt ?? 0).getTime(),
+      }))
+
+      const record = await this.persistPattern({
+        organizationId: orgRef,
+        type: 'timing-pattern',
+        pattern: { runId: params.runId, timings },
+        confidence: 0.7,
+        sampleCount: completedNodes.length,
+      })
+      patterns.push(record)
+    }
+
+    const failedNodes = nodeRuns.filter((nr) => nr.status === 'failed')
+    if (failedNodes.length > 0) {
+      const failures = failedNodes.map((nr) => ({
+        nodeId: nr.nodeId,
+        owner: ownerRef(nr.nodeId),
+        attemptCount: nr.attemptCount,
+      }))
+
+      const record = await this.persistPattern({
+        organizationId: orgRef,
+        type: 'failure-pattern',
+        pattern: { runId: params.runId, failures },
+        confidence: 0.6,
+        sampleCount: failedNodes.length,
+      })
+      patterns.push(record)
+    }
+
+    const agentCompletions = new Map<string, number>()
+    for (const nr of completedNodes) {
+      const owner = ownerRef(nr.nodeId)
+      agentCompletions.set(owner, (agentCompletions.get(owner) ?? 0) + 1)
+    }
+    if (agentCompletions.size > 0) {
+      const record = await this.persistPattern({
+        organizationId: orgRef,
+        type: 'agent-affinity',
+        pattern: { runId: params.runId, completions: Object.fromEntries(agentCompletions) },
+        confidence: 0.5,
+        sampleCount: completedNodes.length,
+      })
+      patterns.push(record)
+    }
+
+    return patterns
+  }
+
+  async queryRelevant(params: {
+    organizationId: string
+    objective: string
+    limit?: number
+  }): Promise<InstitutionalMemory[]> {
+    const orgRef = ensureRecordId(params.organizationId, TABLES.ORGANIZATION)
+    const limit = params.limit ?? 10
+
+    // Fetch a broader set, then rank by relevance to the objective.
+    // SurrealDB does not support full-text scoring on FLEXIBLE object fields,
+    // so we over-fetch and rank in application code.
+    const fetchLimit = Math.max(limit * 3, 30)
+    const records = await databaseService.queryMany(
+      new BoundQuery(
+        `SELECT * FROM ${TABLES.INSTITUTIONAL_MEMORY}
+         WHERE organizationId = $orgId
+         ORDER BY confidence DESC, createdAt DESC
+         LIMIT $fetchLimit`,
+        { orgId: orgRef, fetchLimit },
+      ),
+      InstitutionalMemorySchema,
+    )
+
+    // Score each record by how many objective keywords appear in its pattern JSON
+    const objectiveTerms = params.objective
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 2)
+
+    if (objectiveTerms.length === 0) return records.slice(0, limit)
+
+    const scored = records.map((record) => {
+      const patternStr = JSON.stringify(record.pattern).toLowerCase()
+      const matchCount = objectiveTerms.filter((term) => patternStr.includes(term)).length
+      return { record, relevance: matchCount / objectiveTerms.length }
+    })
+
+    scored.sort((a, b) => {
+      // Primary: relevance score, secondary: confidence, tertiary: recency
+      if (b.relevance !== a.relevance) return b.relevance - a.relevance
+      if (b.record.confidence !== a.record.confidence) return b.record.confidence - a.record.confidence
+      return 0
+    })
+
+    return scored.slice(0, limit).map((s) => s.record)
+  }
+
+  private async persistPattern(params: {
+    organizationId: ReturnType<typeof ensureRecordId>
+    type: InstitutionalMemoryType
+    pattern: Record<string, unknown>
+    confidence: number
+    sampleCount: number
+  }): Promise<InstitutionalMemory> {
+    return databaseService.create(
+      TABLES.INSTITUTIONAL_MEMORY,
+      {
+        organizationId: params.organizationId,
+        type: params.type,
+        pattern: params.pattern,
+        confidence: params.confidence,
+        sampleCount: params.sampleCount,
+      },
+      InstitutionalMemorySchema,
+    )
+  }
+}
+
+export const institutionalMemoryService = new InstitutionalMemoryService()

package/src/services/learned-skill.service.ts

@@ -5,7 +5,7 @@ import { z } from 'zod'
 import { renderLearnedSkillInstructions } from '../ai/definitions'
 import { lotaDebugLogger } from '../config/debug-logger'
 import { serverLogger } from '../config/logger'
-import { ensureRecordId } from '../db/record-id'
+import { ensureRecordId, recordIdToString } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import { getDefaultEmbeddings } from '../embeddings/provider'
@@ -16,6 +16,7 @@ const embeddings = getDefaultEmbeddings()
 const PROMOTION_MIN_USES = 5
 const PROMOTION_MIN_SUCCESS_RATE = 0.6
 
+const ACTIVE_SKILL_FILTER = "AND status IN ['learned', 'verified', 'promoted'] AND archivedAt IS NONE"
 const SKILL_EXISTS_TTL_SECONDS = 120
 const SKILL_EXISTS_KEY_PREFIX = 'skill-exists'
 
@@ -123,7 +124,7 @@ class LearnedSkillService {
 
   async update(skillId: string, input: UpdateLearnedSkillInput): Promise<LearnedSkillRow> {
     const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    const data: Record<string, unknown> = { updatedAt: new Date().toISOString() }
+    const data: Record<string, unknown> = {}
 
     if (input.name !== undefined) data.name = input.name
     if (input.description !== undefined) data.description = input.description
@@ -148,11 +149,11 @@ class LearnedSkillService {
     await databaseService.update(
       TABLES.LEARNED_SKILL,
       ref,
-      { status: 'archived', archivedAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
+      { status: 'archived', archivedAt: new Date() },
       LearnedSkillRowSchema,
     )
     if (skill) {
-      await this.invalidateSkillExistsCache(String(skill.organizationId), skill.agentId ?? null)
+      await this.invalidateSkillExistsCache(recordIdToString(skill.organizationId), skill.agentId ?? null)
     }
   }
 
@@ -176,8 +177,7 @@ class LearnedSkillService {
       new BoundQuery(
         `SELECT id FROM ${TABLES.LEARNED_SKILL}
          WHERE organizationId = $orgRef
-           AND status IN ['learned', 'verified', 'promoted']
-           AND archivedAt IS NONE
+           ${ACTIVE_SKILL_FILTER}
            AND (agentId IS NONE OR agentId = $agentId)
          LIMIT 1`,
         { orgRef, agentId },
@@ -227,8 +227,7 @@ class LearnedSkillService {
         vector::similarity::cosine(embedding, $embedding) AS similarity
       FROM ${TABLES.LEARNED_SKILL}
       WHERE organizationId = $organizationId
-        AND status IN ['learned', 'verified', 'promoted']
-        AND archivedAt IS NONE
+        ${ACTIVE_SKILL_FILTER}
         AND confidence >= $minConfidence
         AND (agentId IS NONE OR agentId = $agentId)
         AND embedding <|${params.limit}|> $embedding
@@ -293,7 +292,7 @@ class LearnedSkillService {
     await databaseService.update(
       TABLES.LEARNED_SKILL,
       ref,
-      { status: 'verified', confidence: Math.min(skill.confidence + 0.1, 1.0), updatedAt: new Date().toISOString() },
+      { status: 'verified', confidence: Math.min(skill.confidence + 0.1, 1.0) },
       LearnedSkillRowSchema,
     )
     return true
@@ -311,8 +310,7 @@ class LearnedSkillService {
         vector::similarity::cosine(embedding, $embedding) AS similarity
       FROM ${TABLES.LEARNED_SKILL}
       WHERE organizationId = $organizationId
-        AND status IN ['learned', 'verified', 'promoted']
-        AND archivedAt IS NONE
+        ${ACTIVE_SKILL_FILTER}
         AND embedding <|3|> $embedding
       ORDER BY similarity DESC
       LIMIT 1
@@ -333,8 +331,7 @@ class LearnedSkillService {
         `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
          FROM ${TABLES.LEARNED_SKILL}
          WHERE organizationId = $organizationId
-           AND status IN ['learned', 'verified', 'promoted']
-           AND archivedAt IS NONE
+           ${ACTIVE_SKILL_FILTER}
          ORDER BY createdAt DESC`,
         { organizationId: orgRef },
       ),
@@ -349,6 +346,25 @@ class LearnedSkillService {
     return hasher.digest('hex')
   }
 
+  async findByNameOrTag(orgId: string, nameOrTag: string): Promise<LearnedSkillRow | null> {
+    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+    const normalizedRef = nameOrTag.trim().toLowerCase()
+    const rows = await databaseService.queryMany(
+      new BoundQuery(
+        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+         FROM ${TABLES.LEARNED_SKILL}
+         WHERE organizationId = $organizationId
+           ${ACTIVE_SKILL_FILTER}
+           AND (string::lowercase(name) = $nameRef OR $nameRef IN tags)
+         ORDER BY confidence DESC
+         LIMIT 1`,
+        { organizationId: orgRef, nameRef: normalizedRef },
+      ),
+      LearnedSkillRowSchema,
+    )
+    return rows[0] ?? null
+  }
+
   async findByHash(orgId: string, hash: string): Promise<LearnedSkillRow | null> {
     const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
     const rows = await databaseService.queryMany(
@@ -357,8 +373,7 @@ class LearnedSkillService {
          FROM ${TABLES.LEARNED_SKILL}
          WHERE organizationId = $organizationId
            AND hash = $hash
-           AND status IN ['learned', 'verified', 'promoted']
-           AND archivedAt IS NONE
+           ${ACTIVE_SKILL_FILTER}
          LIMIT 1`,
         { organizationId: orgRef, hash },
       ),

package/src/services/memory-assessment.service.ts

@@ -3,13 +3,14 @@ import type { z } from 'zod'
 import { MemoryImportanceAssessmentSchema } from '../db/memory-types'
 import { createHelperModelRuntime } from '../runtime/helper-model'
 import { createOrgMemoryAgent } from '../system-agents/memory.agent'
+import { clampImportance } from '../utils/string'
 
 type MemoryImportanceAssessment = z.infer<typeof MemoryImportanceAssessmentSchema>
 const MEMORY_IMPORTANCE_ASSESSMENT_TIMEOUT_MS = 10 * 60 * 1000
 const helperModelRuntime = createHelperModelRuntime()
 
 export function clampMemoryImportance(value: number): number {
-  return Math.max(0.2, Math.min(0.95, value))
+  return clampImportance(Math.max(0.2, Math.min(0.95, value)))
 }
 
 export async function assessMemoryImportance(params: {
@@ -32,7 +33,7 @@ export async function assessMemoryImportance(params: {
     'Return only schema fields.',
   ].join('\n')
 
-  return await helperModelRuntime.generateHelperStructured({
+  return helperModelRuntime.generateHelperStructured({
     tag: params.tag ?? 'memory-importance-assessment',
     createAgent: createOrgMemoryAgent,
     systemPrompt: 'You are a strict long-term memory quality assessor for an AI agent.',

package/src/services/{memory.utils.ts → memory-utils.ts}

@@ -1,25 +1,17 @@
 import { MEMORY } from '../config/constants'
 import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '../config/search'
 import type { MemorySearchResult } from '../db/memory-types'
-import { resolveCandidateLimit } from '../runtime/retrieval-pipeline'
+import { compactWhitespace, truncateText } from '../utils/string'
 import type { MemoryRerankOutput } from './memory.service'
 
 export function getCandidateLimit(limit: number): number {
-  return resolveCandidateLimit({
-    limit,
-    multiplier: VECTOR_SEARCH_OVERFETCH_MULTIPLIER,
-    minimum: MEMORY.DEFAULT_CANDIDATE_LIMIT,
-  })
+  return Math.max(limit * VECTOR_SEARCH_OVERFETCH_MULTIPLIER, MEMORY.DEFAULT_CANDIDATE_LIMIT)
 }
 
 export function formatMemoryResults(results: MemorySearchResult[]): string {
   if (results.length === 0) return 'No stored memories.'
 
-  const normalize = (value: string) => {
-    const trimmed = value.replace(/\s+/g, ' ').trim()
-    if (trimmed.length <= 400) return trimmed
-    return `${trimmed.slice(0, 400)}...`
-  }
+  const normalize = (value: string) => truncateText(compactWhitespace(value), 400)
 
   return results
     .map((item) => {
@@ -65,8 +57,7 @@ export function formatRerankedResults(
       used.add(candidate.id)
       total += 1
       const reason = item.relevance ? ` — ${item.relevance}` : ''
-      const trimmed = candidate.content.replace(/\s+/g, ' ').trim()
-      const content = trimmed.length <= 400 ? trimmed : `${trimmed.slice(0, 400)}...`
+      const content = truncateText(compactWhitespace(candidate.content), 400)
       lines.push(`- ${content}${reason}`)
       if (total >= limit) break
     }