@lota-sdk/core 0.1.14 → 0.1.16

package/src/services/plan-workspace.service.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+
+import { getRedisConnection } from '../redis'
+
+const PlanWorkspaceEntrySchema = z.object({
+  value: z.unknown(),
+  version: z.number(),
+  writeSequence: z.number(),
+  nodeId: z.string(),
+  timestamp: z.number(),
+})
+
+export type PlanWorkspaceEntry = z.infer<typeof PlanWorkspaceEntrySchema>
+
+class PlanWorkspaceService {
+  private keyPrefix = 'plan-workspace:'
+
+  async write(params: {
+    runId: string
+    nodeId: string
+    key: string
+    value: unknown
+    version: number
+    checkpointSequence: number
+  }): Promise<void> {
+    const redis = getRedisConnection()
+    const hashKey = `${this.keyPrefix}${params.runId}`
+    const fieldKey = `${params.nodeId}:${params.key}`
+    const entry: PlanWorkspaceEntry = {
+      value: params.value,
+      version: params.version,
+      writeSequence: params.checkpointSequence,
+      nodeId: params.nodeId,
+      timestamp: Date.now(),
+    }
+    await redis.hset(hashKey, fieldKey, JSON.stringify(entry))
+  }
+
+  async snapshotRead(params: {
+    runId: string
+    readerNodeId: string
+    snapshotSequence?: number
+  }): Promise<Record<string, PlanWorkspaceEntry>> {
+    const redis = getRedisConnection()
+    const hashKey = `${this.keyPrefix}${params.runId}`
+    const nodePrefix = `${params.readerNodeId}:`
+    const all = await redis.hgetall(hashKey)
+    const result: Record<string, PlanWorkspaceEntry> = {}
+    for (const [fieldKey, raw] of Object.entries(all)) {
+      if (!fieldKey.startsWith(nodePrefix)) continue
+      const entry = PlanWorkspaceEntrySchema.parse(JSON.parse(raw))
+      if (params.snapshotSequence !== undefined && entry.writeSequence > params.snapshotSequence) {
+        continue
+      }
+      result[fieldKey] = entry
+    }
+    return result
+  }
+
+  async currentRead(params: { runId: string; key?: string }): Promise<Record<string, PlanWorkspaceEntry>> {
+    const redis = getRedisConnection()
+    const hashKey = `${this.keyPrefix}${params.runId}`
+    if (params.key) {
+      // Support both raw field keys (e.g. 'nodeId:key') and plain keys
+      const raw = await redis.hget(hashKey, params.key)
+      if (!raw) return {}
+      return { [params.key]: PlanWorkspaceEntrySchema.parse(JSON.parse(raw)) }
+    }
+    const all = await redis.hgetall(hashKey)
+    const result: Record<string, PlanWorkspaceEntry> = {}
+    for (const [k, v] of Object.entries(all)) {
+      result[k] = PlanWorkspaceEntrySchema.parse(JSON.parse(v))
+    }
+    return result
+  }
+
+  async cleanup(runId: string): Promise<void> {
+    const redis = getRedisConnection()
+    await redis.del(`${this.keyPrefix}${runId}`)
+  }
+}
+
+export const planWorkspaceService = new PlanWorkspaceService()

package/src/services/playbook-registry.service.ts

@@ -0,0 +1,67 @@
+import type { PlanTemplateRecord } from '@lota-sdk/shared'
+
+import type { RecordIdInput } from '../db/record-id'
+import type { PlaybookContribution } from '../runtime/plugin-types'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+import { planTemplateService } from './plan-template.service'
+
+class PlaybookRegistryService {
+  collectPlaybooks(): PlaybookContribution[] {
+    const plugins = getRuntimeConfig().pluginRuntime ?? {}
+    const playbooks: PlaybookContribution[] = []
+    for (const plugin of Object.values(plugins)) {
+      if (plugin.playbookContributor?.playbooks) {
+        playbooks.push(...plugin.playbookContributor.playbooks)
+      }
+    }
+    return playbooks
+  }
+
+  async syncPlaybookTemplates(organizationId: RecordIdInput): Promise<PlanTemplateRecord[]> {
+    const playbooks = this.collectPlaybooks()
+    const templates: PlanTemplateRecord[] = []
+    const existing = await planTemplateService.listTemplates(organizationId, { source: 'playbook' })
+
+    for (const pb of playbooks) {
+      const match = existing.find((t) => t.sourceRef === pb.name)
+      if (match) {
+        const updated = await planTemplateService.updateTemplate(match.id, { draft: pb.draft, tags: pb.tags })
+        templates.push(updated)
+      } else {
+        const created = await planTemplateService.createTemplate({
+          organizationId,
+          name: pb.name,
+          description: pb.description,
+          draft: pb.draft,
+          tags: pb.tags,
+          source: 'playbook',
+          sourceRef: pb.name,
+        })
+        templates.push(created)
+      }
+    }
+
+    return templates
+  }
+
+  async instantiatePlaybook(params: {
+    name: string
+    organizationId: RecordIdInput
+    workstreamId: RecordIdInput
+    leadAgentId: string
+  }): Promise<unknown> {
+    const templates = await planTemplateService.listTemplates(params.organizationId, { source: 'playbook' })
+    const template = templates.find((t) => t.sourceRef === params.name)
+    if (!template) {
+      throw new Error(`Playbook "${params.name}" not found.`)
+    }
+    return planTemplateService.instantiate({
+      templateId: template.id,
+      organizationId: params.organizationId,
+      workstreamId: params.workstreamId,
+      leadAgentId: params.leadAgentId,
+    })
+  }
+}
+
+export const playbookRegistryService = new PlaybookRegistryService()

package/src/services/plugin-executor.service.ts

@@ -0,0 +1,103 @@
+import type { OwnershipDispatchContext, PlanNodeResult, PlanNodeSpec, PluginPlanNodeOwner } from '@lota-sdk/shared'
+
+import type { LotaPlugin, PluginNodeExecutionParams } from '../runtime/plugin-types'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+function getPluginRuntime() {
+  return (getRuntimeConfig().pluginRuntime ?? {}) as Record<string, LotaPlugin | undefined>
+}
+
+function buildPluginExecutionParams(params: {
+  owner: PluginPlanNodeOwner
+  nodeSpec: PlanNodeSpec
+  resolvedInput: Record<string, unknown>
+  context: OwnershipDispatchContext
+}): PluginNodeExecutionParams {
+  return {
+    operation: params.owner.operation,
+    nodeSpec: params.nodeSpec,
+    inputs: params.resolvedInput,
+    context: {
+      organizationId: params.context.organizationId,
+      workstreamId: params.context.workstreamId,
+      planId: params.context.planId,
+      nodeId: params.context.nodeId,
+      ...(params.context.userId ? { userId: params.context.userId } : {}),
+      ...(params.context.userName ? { userName: params.context.userName } : {}),
+    },
+  }
+}
+
+class PluginExecutorService {
+  validateOwner(owner: PluginPlanNodeOwner, nodeId: string): PlanValidationIssueInput[] {
+    const plugin = getPluginRuntime()[owner.ref]
+    if (!plugin) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_executor_missing',
+          message: `Node "${nodeId}" references unknown plugin executor "${owner.ref}".`,
+          nodeId,
+          detail: { pluginRef: owner.ref },
+        },
+      ]
+    }
+
+    const nodeExecutor = plugin.nodeExecutor
+    if (!nodeExecutor) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_node_executor_missing',
+          message: `Plugin "${owner.ref}" does not expose a node executor.`,
+          nodeId,
+          detail: { pluginRef: owner.ref },
+        },
+      ]
+    }
+
+    if (!nodeExecutor.supportedOperations.includes(owner.operation)) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'plugin_operation_missing',
+          message: `Plugin "${owner.ref}" does not support operation "${owner.operation}".`,
+          nodeId,
+          detail: { pluginRef: owner.ref, operation: owner.operation },
+        },
+      ]
+    }
+
+    return []
+  }
+
+  async executeNode(params: {
+    nodeSpec: PlanNodeSpec
+    resolvedInput: Record<string, unknown>
+    context: OwnershipDispatchContext
+  }): Promise<PlanNodeResult> {
+    if (params.nodeSpec.owner.executorType !== 'plugin') {
+      throw new Error(`PluginExecutor cannot execute owner type "${params.nodeSpec.owner.executorType}".`)
+    }
+
+    const plugin = getPluginRuntime()[params.nodeSpec.owner.ref]
+    const nodeExecutor = plugin?.nodeExecutor
+    if (!plugin || !nodeExecutor || !nodeExecutor.supportedOperations.includes(params.nodeSpec.owner.operation)) {
+      throw new Error(
+        `Plugin executor ${params.nodeSpec.owner.ref}.${params.nodeSpec.owner.operation} is not registered.`,
+      )
+    }
+
+    return nodeExecutor.executeNode(
+      buildPluginExecutionParams({
+        owner: params.nodeSpec.owner,
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      }),
+    )
+  }
+}
+
+export const pluginExecutorService = new PluginExecutorService()

package/src/services/quality-metrics.service.ts

@@ -0,0 +1,132 @@
+import { NodeQualityMetricsSchema } from '@lota-sdk/shared'
+import type { NodeQualityMetrics } from '@lota-sdk/shared'
+import { z } from 'zod'
+
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+
+const QualityMetricRowSchema = NodeQualityMetricsSchema.extend({
+  id: z.unknown(),
+  organizationId: z.unknown(),
+  runId: z.unknown(),
+  nodeId: z.string().optional(),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+})
+
+class QualityMetricsService {
+  async recordNodeMetrics(params: {
+    organizationId: string
+    runId: string
+    nodeId: string
+    metrics: NodeQualityMetrics
+  }): Promise<void> {
+    await databaseService.create(
+      TABLES.QUALITY_METRIC,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        nodeId: params.nodeId,
+        ownerRef: params.metrics.ownerRef,
+        ownerType: params.metrics.ownerType,
+        nodeType: params.metrics.nodeType,
+        executionTimeMs: params.metrics.executionTimeMs,
+        attemptCount: params.metrics.attemptCount,
+        artifactCount: params.metrics.artifactCount,
+        validationIssueCount: params.metrics.validationIssueCount,
+      },
+      QualityMetricRowSchema,
+    )
+  }
+
+  async recordCycleMetrics(params: { organizationId: string; runId: string }): Promise<void> {
+    const existing = await databaseService.findMany(
+      TABLES.QUALITY_METRIC,
+      { runId: ensureRecordId(params.runId, TABLES.PLAN_RUN) },
+      QualityMetricRowSchema,
+      { orderBy: 'createdAt', orderDir: 'ASC' },
+    )
+
+    if (!Array.isArray(existing) || existing.length === 0) return
+
+    const totalExecutionTime = existing.reduce(
+      (sum, m) => sum + (typeof m.executionTimeMs === 'number' ? m.executionTimeMs : 0),
+      0,
+    )
+    const totalAttempts = existing.reduce(
+      (sum, m) => sum + (typeof m.attemptCount === 'number' ? m.attemptCount : 0),
+      0,
+    )
+    const totalIssues = existing.reduce(
+      (sum, m) => sum + (typeof m.validationIssueCount === 'number' ? m.validationIssueCount : 0),
+      0,
+    )
+
+    await databaseService.create(
+      TABLES.QUALITY_METRIC,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        runId: ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        ownerRef: 'cycle-summary',
+        ownerType: 'system',
+        nodeType: 'action',
+        executionTimeMs: totalExecutionTime,
+        attemptCount: totalAttempts,
+        artifactCount: existing.length,
+        validationIssueCount: totalIssues,
+      },
+      QualityMetricRowSchema,
+    )
+  }
+
+  detectRegression(params: {
+    metrics: Array<{ executionTimeMs: number; validationIssueCount: number }>
+    window?: number
+  }): { detected: boolean; trend?: 'improving' | 'stable' | 'regressing' } {
+    const window = params.window ?? 5
+    const recent = params.metrics.slice(-window)
+    if (recent.length < 2) return { detected: false, trend: 'stable' }
+
+    const mid = Math.floor(recent.length / 2)
+    const firstHalf = recent.slice(0, mid)
+    const secondHalf = recent.slice(mid)
+
+    const avgFirst = firstHalf.reduce((sum, m) => sum + m.validationIssueCount, 0) / firstHalf.length
+    const avgSecond = secondHalf.reduce((sum, m) => sum + m.validationIssueCount, 0) / secondHalf.length
+
+    const timeFirst = firstHalf.reduce((sum, m) => sum + m.executionTimeMs, 0) / firstHalf.length
+    const timeSecond = secondHalf.reduce((sum, m) => sum + m.executionTimeMs, 0) / secondHalf.length
+
+    const issueRegression = avgFirst > 0 && avgSecond > avgFirst * 1.5
+    const timeRegression = timeFirst > 0 && timeSecond > timeFirst * 2
+
+    if (issueRegression || timeRegression) {
+      return { detected: true, trend: 'regressing' }
+    }
+
+    const issueImproving = avgFirst > 0 && avgSecond < avgFirst * 0.7
+    const timeImproving = timeFirst > 0 && timeSecond < timeFirst * 0.7
+
+    if (issueImproving || timeImproving) {
+      return { detected: false, trend: 'improving' }
+    }
+
+    return { detected: false, trend: 'stable' }
+  }
+
+  async getMetricsByOwner(params: {
+    organizationId: string
+    ownerRef: string
+    limit?: number
+  }): Promise<z.infer<typeof QualityMetricRowSchema>[]> {
+    return databaseService.findMany(
+      TABLES.QUALITY_METRIC,
+      { organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION), ownerRef: params.ownerRef },
+      QualityMetricRowSchema,
+      { orderBy: 'createdAt', orderDir: 'DESC', limit: params.limit ?? 20 },
+    )
+  }
+}
+
+export const qualityMetricsService = new QualityMetricsService()

package/src/services/recent-activity-title.service.ts

@@ -1,20 +1,13 @@
 import { createHelperModelRuntime } from '../runtime/helper-model'
+import { normalizeTitle } from '../runtime/title-helpers'
 import {
   createRecentActivityTitleRefinerAgent,
-  recentActivityTitleRefinerPrompt,
+  RECENT_ACTIVITY_TITLE_REFINER_PROMPT,
 } from '../system-agents/recent-activity-title-refiner.agent'
-import { compactWhitespace } from '../utils/string'
 import { recentActivityService } from './recent-activity.service'
 
 const RECENT_ACTIVITY_TITLE_TIMEOUT_MS = 60_000
 
-function normalizeTitle(value: string): string {
-  const normalized = compactWhitespace(value)
-    .replace(/^["'`]+|["'`]+$/g, '')
-    .replace(/[.!?,;:]+$/g, '')
-  return normalized.length <= 80 ? normalized : normalized.slice(0, 80).trim()
-}
-
 function buildRefinementPromptInput(
   candidate: Awaited<ReturnType<typeof recentActivityService.getRefinementCandidate>>,
 ) {
@@ -52,7 +45,7 @@ class RecentActivityTitleService {
       await this.helperRuntime.generateHelperText({
         tag: 'recent-activity-title-refinement',
         createAgent: createRecentActivityTitleRefinerAgent,
-        defaultSystemPrompt: recentActivityTitleRefinerPrompt,
+        defaultSystemPrompt: RECENT_ACTIVITY_TITLE_REFINER_PROMPT,
         timeoutMs: RECENT_ACTIVITY_TITLE_TIMEOUT_MS,
         messages: [{ role: 'user', content: promptInput }],
       }),

package/src/services/recent-activity.service.ts

@@ -8,6 +8,7 @@ import {
   RecentActivitySchema,
   RecentActivitySourceSchema,
   RecentActivityTitleSourceSchema,
+  recordIdSchema,
 } from '@lota-sdk/shared'
 import type {
   RecentActivity,
@@ -23,12 +24,12 @@ import type { RecordIdInput, RecordIdRef } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
-import { compactWhitespace } from '../utils/string'
+import { compactRecord, compactWhitespace, truncateText } from '../utils/string'
 
 const RecentActivityEventRowSchema = z.object({
-  id: z.unknown(),
-  organizationId: z.unknown(),
-  userId: z.unknown(),
+  id: recordIdSchema,
+  organizationId: recordIdSchema,
+  userId: recordIdSchema,
   sourceEventId: z.string(),
   source: RecentActivitySourceSchema,
   kind: RecentActivityEventInputSchema.shape.kind,
@@ -39,14 +40,14 @@ const RecentActivityEventRowSchema = z.object({
   sourceLabel: z.string(),
   deepLink: RecentActivityDeepLinkSchema,
   metadata: RecentActivityMetadataSchema.optional(),
-  occurredAt: z.union([z.string(), z.date(), z.number()]),
-  createdAt: z.union([z.string(), z.date(), z.number()]),
+  occurredAt: z.coerce.date(),
+  createdAt: z.coerce.date(),
 })
 
 const RecentActivityRowSchema = z.object({
-  id: z.unknown(),
-  organizationId: z.unknown(),
-  userId: z.unknown(),
+  id: recordIdSchema,
+  organizationId: recordIdSchema,
+  userId: recordIdSchema,
   mergeKey: z.string(),
   kind: RecentActivityEventInputSchema.shape.kind,
   targetKind: RecentActivityEventInputSchema.shape.targetKind,
@@ -57,27 +58,17 @@ const RecentActivityRowSchema = z.object({
   sourceLabel: z.string(),
   deepLink: RecentActivityDeepLinkSchema,
   metadata: RecentActivityMetadataSchema.optional(),
-  latestEventId: z.unknown().optional(),
+  latestEventId: recordIdSchema.optional(),
   latestSourceEventId: z.string().optional(),
-  latestEventAt: z.union([z.string(), z.date(), z.number()]),
-  titleRefinedAt: z.union([z.string(), z.date(), z.number()]).optional(),
-  createdAt: z.union([z.string(), z.date(), z.number()]),
-  updatedAt: z.union([z.string(), z.date(), z.number()]),
+  latestEventAt: z.coerce.date(),
+  titleRefinedAt: z.coerce.date().optional(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
 })
 
 type RecentActivityEventRow = z.infer<typeof RecentActivityEventRowSchema>
 type RecentActivityRow = z.infer<typeof RecentActivityRowSchema>
 
-function compactRecord(value: Record<string, unknown>): Record<string, unknown> {
-  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== null && entry !== undefined))
-}
-
-function clampText(value: string, maxLength: number): string {
-  const normalized = compactWhitespace(value)
-  if (normalized.length <= maxLength) return normalized
-  return normalized.slice(0, maxLength).trim()
-}
-
 function buildDeterministicRecordId(table: string, key: string): RecordId {
   const digest = createHash('sha256').update(key).digest('hex')
   return new RecordId(table, digest)
@@ -90,6 +81,11 @@ function shouldKeepExistingAgentTitle(existing: RecentActivityRow | null): boole
 function buildRecentActivityAreaKey(
   row: Pick<RecentActivityRow, 'targetKind' | 'targetId' | 'kind' | 'mergeKey' | 'metadata'>,
 ): string {
+  const workstreamId = row.metadata?.workstreamId
+  if (workstreamId) {
+    return `workstream:${compactWhitespace(workstreamId)}`
+  }
+
   if (row.targetId) {
     return `${row.targetKind}:${row.targetId}`
   }
@@ -149,11 +145,11 @@ class RecentActivityService {
   private sanitizeEvent(input: RecentActivityEventInput): RecentActivityEventInput {
     return {
       ...input,
-      sourceEventId: clampText(input.sourceEventId, 200),
-      ...(input.targetId ? { targetId: clampText(input.targetId, 200) } : {}),
-      mergeKey: clampText(input.mergeKey, 200),
-      title: clampText(input.title, 140),
-      sourceLabel: clampText(input.sourceLabel, 40),
+      sourceEventId: truncateText(input.sourceEventId, 200),
+      ...(input.targetId ? { targetId: truncateText(input.targetId, 200) } : {}),
+      mergeKey: truncateText(input.mergeKey, 200),
+      title: truncateText(input.title, 140),
+      sourceLabel: truncateText(input.sourceLabel, 40),
       ...(input.metadata ? { metadata: RecentActivityMetadataSchema.parse(input.metadata) } : {}),
     }
   }
@@ -166,18 +162,12 @@ class RecentActivityService {
   }): Promise<RecentActivity[]> {
     await databaseService.connect()
 
-    const items: RecentActivity[] = []
-    for (const candidate of params.events) {
-      const recorded = await this.recordEvent({
-        orgId: params.orgId,
-        userId: params.userId,
-        source: params.source,
-        event: candidate,
-      })
-      items.push(recorded.item)
-    }
-
-    return items
+    const results = await Promise.all(
+      params.events.map((candidate) =>
+        this.recordEvent({ orgId: params.orgId, userId: params.userId, source: params.source, event: candidate }),
+      ),
+    )
+    return results.map((r) => r.item)
   }
 
   async recordEvent(params: {
@@ -315,7 +305,7 @@ class RecentActivityService {
     const existing = await databaseService.findOne(TABLES.RECENT_ACTIVITY, { id: activityRef }, RecentActivityRowSchema)
     if (!existing) return null
 
-    const nextTitle = clampText(params.title, 80)
+    const nextTitle = truncateText(params.title, 80)
     if (!nextTitle) return this.toPublicItem(existing)
     if (compactWhitespace(nextTitle).toLowerCase() === compactWhitespace(existing.title).toLowerCase()) {
       return this.toPublicItem(existing)
@@ -353,7 +343,7 @@ class RecentActivityService {
       systemTitle: row.systemTitle,
       sourceLabel: row.sourceLabel,
       kind: row.kind,
-      metadata: RecentActivityMetadataSchema.parse(row.metadata ?? {}),
+      metadata: RecentActivityMetadataSchema.parse(row.metadata),
     }
   }
 

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

@@ -0,0 +1,19 @@
+class SkillResolverService {
+  async resolve(params: {
+    skillRef: string
+    organizationId: string
+  }): Promise<{ executorType: 'agent' | 'plugin'; ref: string; operation?: string } | null> {
+    // Dynamic import to avoid circular dependencies and enable testability
+    const { learnedSkillService } = await import('./learned-skill.service')
+    const skill = await learnedSkillService.findByNameOrTag(params.organizationId, params.skillRef)
+    if (!skill) return null
+
+    if (skill.agentId) {
+      return { executorType: 'agent', ref: skill.agentId }
+    }
+
+    return null
+  }
+}
+
+export const skillResolverService = new SkillResolverService()

package/src/services/system-executor.service.ts

@@ -0,0 +1,105 @@
+import type { OwnershipDispatchContext, PlanNodeResult, PlanNodeSpec, SystemPlanNodeOwner } from '@lota-sdk/shared'
+
+import type { SystemNodeExecutor, PluginNodeExecutionParams } from '../runtime/plugin-types'
+import { getRuntimeConfig } from '../runtime/runtime-config'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+
+const BUILT_IN_SYSTEM_EXECUTORS = Object.freeze({
+  'plan-runtime': {
+    supportedOperations: ['echo-input'],
+    async executeNode(params: PluginNodeExecutionParams): Promise<PlanNodeResult> {
+      return { structuredOutput: structuredClone(params.inputs), artifacts: [] }
+    },
+  } satisfies SystemNodeExecutor,
+})
+
+export function getBuiltInSystemExecutors(): Record<string, SystemNodeExecutor> {
+  return Object.fromEntries(Object.entries(BUILT_IN_SYSTEM_EXECUTORS))
+}
+
+function getSystemExecutors() {
+  return (getRuntimeConfig().systemExecutors ?? getBuiltInSystemExecutors()) as Record<
+    string,
+    SystemNodeExecutor | undefined
+  >
+}
+
+function buildSystemExecutionParams(params: {
+  owner: SystemPlanNodeOwner
+  nodeSpec: PlanNodeSpec
+  resolvedInput: Record<string, unknown>
+  context: OwnershipDispatchContext
+}): PluginNodeExecutionParams {
+  return {
+    operation: params.owner.operation,
+    nodeSpec: params.nodeSpec,
+    inputs: params.resolvedInput,
+    context: {
+      organizationId: params.context.organizationId,
+      workstreamId: params.context.workstreamId,
+      planId: params.context.planId,
+      nodeId: params.context.nodeId,
+      ...(params.context.userId ? { userId: params.context.userId } : {}),
+      ...(params.context.userName ? { userName: params.context.userName } : {}),
+    },
+  }
+}
+
+class SystemExecutorService {
+  validateOwner(owner: SystemPlanNodeOwner, nodeId: string): PlanValidationIssueInput[] {
+    const executor = getSystemExecutors()[owner.ref]
+    if (!executor) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'system_executor_missing',
+          message: `Node "${nodeId}" references unknown system executor "${owner.ref}".`,
+          nodeId,
+          detail: { systemRef: owner.ref },
+        },
+      ]
+    }
+
+    if (!executor.supportedOperations.includes(owner.operation)) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'system_operation_missing',
+          message: `System executor "${owner.ref}" does not support operation "${owner.operation}".`,
+          nodeId,
+          detail: { systemRef: owner.ref, operation: owner.operation },
+        },
+      ]
+    }
+
+    return []
+  }
+
+  async executeNode(params: {
+    nodeSpec: PlanNodeSpec
+    resolvedInput: Record<string, unknown>
+    context: OwnershipDispatchContext
+  }): Promise<PlanNodeResult> {
+    if (params.nodeSpec.owner.executorType !== 'system') {
+      throw new Error(`SystemExecutor cannot execute owner type "${params.nodeSpec.owner.executorType}".`)
+    }
+
+    const executor = getSystemExecutors()[params.nodeSpec.owner.ref]
+    if (!executor || !executor.supportedOperations.includes(params.nodeSpec.owner.operation)) {
+      throw new Error(
+        `System executor ${params.nodeSpec.owner.ref}.${params.nodeSpec.owner.operation} is not registered.`,
+      )
+    }
+
+    return executor.executeNode(
+      buildSystemExecutionParams({
+        owner: params.nodeSpec.owner,
+        nodeSpec: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        context: params.context,
+      }),
+    )
+  }
+}
+
+export const systemExecutorService = new SystemExecutorService()