@lota-sdk/core 0.1.15 → 0.1.16

package/src/runtime/execution-plan.ts

@@ -2,16 +2,18 @@ import type { SerializableExecutionPlan } from '@lota-sdk/shared'
 
 const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - Before doing multi-step work, create a contract-driven execution plan instead of tracking steps only in prose.
+- A workstream may have multiple active execution plans. Review all plans before creating new ones.
 - Plans are graph-capable workflow contracts. Every execution node must define objective, instructions, deliverables, success criteria, completion checks, retry policy, failure policy, and tool/context policy.
 - The runtime executor owns lifecycle truth. Do not claim that a node is complete until submitExecutionNodeResult succeeds.
-- Use execution-plan tools to create, replace, inspect, submit node results, and resume runs.
-- Treat the active execution run in <execution-plan-state> as authoritative. Do not mutate run or node status in prose.
+- Use execution-plan tools to create, replace, inspect, and resume runs.
+- Visible workstream agents do not manually submit node results; dispatched execution nodes are completed by the runtime executor.
+- Treat the active execution runs in <execution-plan-state> as authoritative. Do not mutate run or node status in prose.
 - Work only on nodes that are active or explicitly ready for your executor. If a node is awaiting human input or approval, stop and let the runtime resume it.
 - If the graph, contracts, or success criteria materially change, replace the plan instead of silently drifting.
 </execution-plan-protocol>`
 
-function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | undefined): string | undefined {
-  if (!plan) return undefined
+function formatExecutionPlansForPrompt(plans: SerializableExecutionPlan[]): string | undefined {
+  if (plans.length === 0) return undefined
 
   const payload = {
     policy: {
@@ -21,46 +23,48 @@ function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | u
       artifactsAreFirstClassOutputs: true,
       checkpointRecoveryEnabled: true,
     },
-    plan,
+    activePlans: plans,
+    planCount: plans.length,
   }
 
   return ['<execution-plan-state>', JSON.stringify(payload, null, 2), '</execution-plan-state>'].join('\n')
 }
 
 export function buildExecutionPlanInstructionSections(
-  plan: SerializableExecutionPlan | null | undefined,
+  plans: SerializableExecutionPlan[] | null | undefined,
 ): string[] | undefined {
+  const normalized = plans ?? []
   const sections = [EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT]
-  const executionPlanStateSection = formatExecutionPlanForPrompt(plan)
-  if (executionPlanStateSection) {
-    sections.push(executionPlanStateSection)
+  const stateSection = formatExecutionPlansForPrompt(normalized)
+  if (stateSection) {
+    sections.push(stateSection)
   }
   return sections
 }
 
 export function createExecutionPlanInstructionSectionCache(params: {
   disabled?: boolean
-  loadPlan: () => Promise<SerializableExecutionPlan | null | undefined>
+  loadPlans: () => Promise<SerializableExecutionPlan[]>
 }) {
-  let planPromise: Promise<SerializableExecutionPlan | null | undefined> | null = null
+  let plansPromise: Promise<SerializableExecutionPlan[]> | null = null
   let sectionsPromise: Promise<string[] | undefined> | null = null
 
   return {
     invalidate() {
-      planPromise = null
+      plansPromise = null
       sectionsPromise = null
     },
-    async getPlan(): Promise<SerializableExecutionPlan | null | undefined> {
-      if (params.disabled) return undefined
+    async getPlans(): Promise<SerializableExecutionPlan[]> {
+      if (params.disabled) return []
 
-      planPromise ??= params.loadPlan()
-      return await planPromise
+      plansPromise ??= params.loadPlans()
+      return plansPromise
     },
     async getSections(): Promise<string[] | undefined> {
       if (params.disabled) return undefined
 
-      sectionsPromise ??= this.getPlan().then((plan) => buildExecutionPlanInstructionSections(plan))
-      return await sectionsPromise
+      sectionsPromise ??= this.getPlans().then((plans) => buildExecutionPlanInstructionSections(plans))
+      return sectionsPromise
     },
   }
 }

package/src/runtime/graph-designer.ts

@@ -0,0 +1,15 @@
+import type { GraphDesignRequest, GraphDesignResponse } from '@lota-sdk/shared'
+
+export interface GraphDesigner {
+  designGraph(request: GraphDesignRequest): Promise<GraphDesignResponse>
+}
+
+let _graphDesigner: GraphDesigner | null = null
+
+export function configureGraphDesigner(designer: GraphDesigner): void {
+  _graphDesigner = designer
+}
+
+export function getGraphDesigner(): GraphDesigner | null {
+  return _graphDesigner
+}

package/src/runtime/helper-model.ts

@@ -7,7 +7,7 @@ import type {
 } from 'ai'
 import type { ZodSchema } from 'zod'
 
-import { compactWhitespace } from '../utils/string'
+import { isRecord, stringifyUnknown } from '../utils/string'
 
 export interface HelperToolLoopAgentOptions {
   instructions?: string
@@ -49,12 +49,6 @@ export interface GenerateHelperTextParams {
 export interface GenerateHelperStructuredParams<T> extends Omit<GenerateHelperTextParams, 'tag'> {
   tag: string
   schema: ZodSchema<T>
-  textFallbackParser?: (text: string) => T | null
-  normalizeCandidate?: (candidate: unknown) => unknown
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
 function getNumericField(value: Record<string, unknown>, key: string): number | null {
@@ -68,7 +62,7 @@ function getNumericField(value: Record<string, unknown>, key: string): number |
 }
 
 function getErrorStatus(error: unknown): number | null {
-  if (!isObject(error)) return null
+  if (!isRecord(error)) return null
   return getNumericField(error, 'status') ?? getNumericField(error, 'statusCode')
 }
 
@@ -76,44 +70,11 @@ function isRateLimitError(error: unknown): boolean {
   return getErrorStatus(error) === 429
 }
 
-function stringifyUnknown(value: unknown, maxChars: number): string | null {
-  if (value === null || value === undefined) return null
-  const raw = (() => {
-    if (typeof value === 'string') return value
-    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
-      return String(value)
-    }
-    if (typeof value === 'symbol') return value.description ? `Symbol(${value.description})` : 'Symbol()'
-    if (typeof value === 'function') return value.name ? `[function ${value.name}]` : '[function anonymous]'
-    if (Array.isArray(value)) {
-      try {
-        return JSON.stringify(value)
-      } catch {
-        return `[array(${value.length})]`
-      }
-    }
-
-    try {
-      return JSON.stringify(value)
-    } catch {
-      const maybeName =
-        isObject(value) && typeof (value as { constructor?: { name?: unknown } }).constructor?.name === 'string'
-          ? (value as { constructor?: { name?: string } }).constructor?.name
-          : 'Object'
-      return `[object ${maybeName}]`
-    }
-  })()
-
-  const normalized = compactWhitespace(raw)
-  if (!normalized) return null
-  return normalized.length > maxChars ? `${normalized.slice(0, maxChars)}...` : normalized
-}
-
 function formatError(tag: string, error: unknown): Error {
   const status = getErrorStatus(error)
   const rateLimited = isRateLimitError(error)
   const message = error instanceof Error ? error.message : String(error)
-  const errorRecord = isObject(error) ? error : null
+  const errorRecord = isRecord(error) ? error : null
   const responseBody = errorRecord ? stringifyUnknown(errorRecord.responseBody, 600) : null
   const responseData = errorRecord ? stringifyUnknown(errorRecord.data, 600) : null
   const requestUrl = errorRecord ? stringifyUnknown(errorRecord.url, 200) : null
@@ -164,59 +125,6 @@ function formatSchemaIssueSummary(issues: Array<{ path: PropertyKey[]; message:
     .join('; ')
 }
 
-export function extractJsonObjectCandidates(text: string): string[] {
-  const trimmed = text.trim()
-  if (!trimmed) return []
-
-  const candidates: string[] = [trimmed]
-  const fencedMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i)
-  if (fencedMatch?.[1]) {
-    candidates.push(fencedMatch[1].trim())
-  }
-
-  let start = -1
-  let depth = 0
-  let inString = false
-  let escaping = false
-
-  for (let index = 0; index < trimmed.length; index += 1) {
-    const character = trimmed[index]
-
-    if (escaping) {
-      escaping = false
-      continue
-    }
-
-    if (character === '\\') {
-      escaping = true
-      continue
-    }
-
-    if (character === '"') {
-      inString = !inString
-      continue
-    }
-
-    if (inString) continue
-
-    if (character === '{') {
-      if (depth === 0) start = index
-      depth += 1
-      continue
-    }
-
-    if (character === '}') {
-      depth -= 1
-      if (depth === 0 && start >= 0) {
-        candidates.push(trimmed.slice(start, index + 1))
-        start = -1
-      }
-    }
-  }
-
-  return [...new Set(candidates.filter((candidate) => candidate.length > 0))]
-}
-
 function parseStructuredCandidate<T>(params: {
   schema: ZodSchema<T>
   candidate: unknown
@@ -226,7 +134,7 @@ function parseStructuredCandidate<T>(params: {
     return { data: direct.data, source: 'root' }
   }
 
-  if (isObject(params.candidate)) {
+  if (isRecord(params.candidate)) {
     for (const key of ['output', 'result', 'data'] as const) {
       const nested = params.candidate[key]
       const nestedParsed = params.schema.safeParse(nested)
@@ -239,66 +147,6 @@ function parseStructuredCandidate<T>(params: {
   return null
 }
 
-function parseStructuredTextFallback<T>(params: { schema: ZodSchema<T>; text: string }): T {
-  const candidates = extractJsonObjectCandidates(params.text)
-  if (candidates.length === 0) {
-    throw new Error('Structured fallback did not contain a JSON object candidate.')
-  }
-
-  let lastError = 'Structured fallback could not be parsed.'
-
-  for (const candidateText of candidates) {
-    let parsedJson: unknown
-
-    try {
-      parsedJson = JSON.parse(candidateText) as unknown
-    } catch {
-      lastError = 'Structured fallback JSON parsing failed.'
-      continue
-    }
-
-    const parsed = parseStructuredCandidate({ schema: params.schema, candidate: parsedJson })
-    if (parsed) {
-      return parsed.data
-    }
-
-    const issues = params.schema.safeParse(parsedJson)
-    if (!issues.success) {
-      lastError = `Structured fallback failed schema validation: ${formatSchemaIssueSummary(issues.error.issues)}`
-    }
-  }
-
-  throw new Error(lastError)
-}
-
-function parseStructuredTextWithFallbacks<T>(params: {
-  schema: ZodSchema<T>
-  text: string
-  textFallbackParser?: (text: string) => T | null
-}): T {
-  try {
-    return parseStructuredTextFallback({ schema: params.schema, text: params.text })
-  } catch (error) {
-    const parseError = error instanceof Error ? error : new Error(String(error))
-
-    if (params.textFallbackParser) {
-      const parsedCandidate = params.textFallbackParser(params.text)
-      if (parsedCandidate !== null) {
-        const validated = params.schema.safeParse(parsedCandidate)
-        if (validated.success) {
-          return validated.data
-        }
-
-        throw new Error(
-          `Custom text fallback failed schema validation: ${formatSchemaIssueSummary(validated.error.issues)}`,
-        )
-      }
-    }
-
-    throw parseError
-  }
-}
-
 export function createHelperModelRuntime() {
   async function generateHelperText(params: GenerateHelperTextParams): Promise<string> {
     const systemPrompt = resolveSystemPrompt({
@@ -361,52 +209,16 @@ 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,
-          text: result.text,
-          textFallbackParser: params.textFallbackParser,
-        })
-      }
-
-      const fallbackParsed = params.schema.safeParse(result.output)
-      if (!fallbackParsed.success) {
+      const directParsed = params.schema.safeParse(result.output)
+      if (!directParsed.success) {
         throw new Error(
-          `Structured output failed schema validation: ${formatSchemaIssueSummary(fallbackParsed.error.issues)}`,
+          `Structured output failed schema validation: ${formatSchemaIssueSummary(directParsed.error.issues)}`,
         )
       }
 
-      return fallbackParsed.data
+      return directParsed.data
     } catch (error) {
-      const structuredError = formatError(params.tag, error)
-      const fallbackMessages: string[] = []
-      const fallbackPrompts = [
-        systemPrompt,
-        ...(baseSystemPrompt && baseSystemPrompt !== systemPrompt ? [baseSystemPrompt] : []),
-      ]
-
-      for (const fallbackPrompt of fallbackPrompts) {
-        try {
-          const fallbackText = await generateHelperText({ ...params, systemPrompt: fallbackPrompt })
-          return parseStructuredTextWithFallbacks({
-            schema: params.schema,
-            text: fallbackText,
-            textFallbackParser: params.textFallbackParser,
-          })
-        } catch (fallbackError) {
-          fallbackMessages.push(fallbackError instanceof Error ? fallbackError.message : String(fallbackError))
-        }
-      }
-
-      throw new Error(`${structuredError.message}; structured_fallback=${fallbackMessages.join(' | ')}`)
+      throw formatError(params.tag, error)
     }
   }
 

package/src/runtime/index.ts

@@ -6,6 +6,7 @@ export * from './chat-request-routing'
 export * from './chat-run-registry'
 export * from './context-compaction'
 export * from './execution-plan'
+export * from './graph-designer'
 export * from './helper-model'
 export * from './indexed-repositories-policy'
 export * from './instruction-sections'
@@ -13,6 +14,7 @@ export * from './memory-block'
 export * from './memory-digest-policy'
 export * from './memory-scope'
 export * from './llm-content'
+export * from './plugin-resolution'
 export * from './plugin-types'
 export * from './runtime-config'
 export * from './runtime-extensions'

package/src/runtime/llm-content.ts

@@ -3,7 +3,7 @@ export function stripMemr3Sections(text: string): string {
   const answerMatch = normalized.match(/\[ANSWER\]\s*\n([\s\S]*)/i)
 
   if (answerMatch) {
-    return answerMatch[1]?.trim() ?? ''
+    return answerMatch[1].trim()
   }
 
   return normalized

package/src/runtime/memory-block.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod'
+
 import { agentDisplayNames, agentShortDisplayNames, resolveAgentNameAlias } from '../config/agent-defaults'
 import { compactWhitespace } from '../utils/string'
 
@@ -33,11 +35,9 @@ function createLabelPrefixRegex(labelRoles: readonly string[]): RegExp | null {
   return new RegExp(`^(?:${aliases.map((role) => escapeRegex(role)).join('|')})\\s*:\\s*`, 'i')
 }
 
-export interface MemoryBlockEntry {
-  role: string
-  content: string
-  timestamp: string
-}
+const MemoryBlockEntrySchema = z.object({ role: z.string(), content: z.string(), timestamp: z.string() })
+
+export type MemoryBlockEntry = z.infer<typeof MemoryBlockEntrySchema>
 
 export interface MemoryBlockRuntime {
   normalizeMemoryBlockEntry: (entry: string) => string
@@ -184,10 +184,8 @@ export function createMemoryBlockRuntime(options: CreateMemoryBlockRuntimeOption
     const trimmed = raw.trim()
     if (!trimmed.startsWith('[')) return []
     try {
-      const parsed: unknown = JSON.parse(trimmed)
-      if (!Array.isArray(parsed)) return []
-      if (!parsed.every((item: unknown) => typeof item === 'object' && item !== null)) return []
-      return parsed as MemoryBlockEntry[]
+      const parsed = z.array(MemoryBlockEntrySchema).safeParse(JSON.parse(trimmed))
+      return parsed.success ? parsed.data : []
     } catch {
       return []
     }
@@ -214,8 +212,8 @@ export function createMemoryBlockRuntime(options: CreateMemoryBlockRuntimeOption
       .some((line) => {
         const match = line.match(/^([a-z][a-z0-9_ -]*)\s*:\s*(.+)$/i)
         if (!match) return false
-        const rowRole = normalizeMemoryBlockRole(match[1] ?? '')
-        const rowContent = match[2] ?? ''
+        const rowRole = normalizeMemoryBlockRole(match[1])
+        const rowContent = match[2]
         if (rowRole !== roleLower) return false
         return normalizeMemoryBlockEntry(rowContent) === normalizedTarget
       })

package/src/runtime/memory-pipeline.ts

@@ -1,8 +1,8 @@
-import { compactWhitespace } from '../utils/string'
+import { clampImportance, compactWhitespace } from '../utils/string'
 
 const SCORE_WEIGHTS = {
   durability: { core: 0.35, standard: 0.2, weak: 0.05 },
-  type: { decision: 0.25, preference: 0.18, default: 0.1 },
+  type: { decision: 0.25, fact: 0.18, preference: 0.15, default: 0.1 },
   maxContentLength: 120,
 } as const
 
@@ -107,11 +107,6 @@ interface MemoryActionPlan<TRelation extends string = string> {
   relations: MemoryActionRelation<TRelation>[]
 }
 
-function clampImportance(value: number): number {
-  if (!Number.isFinite(value)) return 0
-  return Math.max(0, Math.min(1, value))
-}
-
 function normalizeMemoryKey(text: string): string {
   return text
     .toLowerCase()
@@ -135,8 +130,10 @@ function scoreFact<T extends MemoryFactInput>(fact: T): number {
     type === 'decision'
       ? SCORE_WEIGHTS.type.decision
       : type === 'fact'
-        ? SCORE_WEIGHTS.type.preference
-        : SCORE_WEIGHTS.type.default
+        ? SCORE_WEIGHTS.type.fact
+        : type === 'preference'
+          ? SCORE_WEIGHTS.type.preference
+          : SCORE_WEIGHTS.type.default
   const lengthWeight =
     Math.min(fact.content.length, SCORE_WEIGHTS.maxContentLength) / SCORE_WEIGHTS.maxContentLength / 10
 

package/src/runtime/plugin-resolution.ts

@@ -0,0 +1,35 @@
+import { pluginRuntime } from '../config/agent-defaults'
+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
+  }
+
+  return owner && typeof owner === 'object'
+    ? (current as (...args: unknown[]) => unknown).bind(owner)
+    : (current as (...args: unknown[]) => unknown)
+}
+
+export async function buildIndexedRepositoriesContext(
+  organizationId: string,
+): Promise<{ provideRepoTool: boolean; defaultSectionsByAgent: Record<string, unknown>; context: string }> {
+  const buildContext = getRuntimeAdapters().workstream?.buildIndexedRepositoriesContext
+  if (!buildContext) {
+    return { provideRepoTool: false, defaultSectionsByAgent: {}, context: '' }
+  }
+
+  const result = await buildContext(organizationId)
+  return {
+    provideRepoTool: result.provideRepoTool,
+    defaultSectionsByAgent: result.defaultSectionsByAgent,
+    context: result.context ?? '',
+  }
+}

package/src/runtime/plugin-types.ts

@@ -1,10 +1,82 @@
+import type {
+  CarryForwardPolicy,
+  CycleSchedule,
+  PlanDraft,
+  PlanNodeResult,
+  PlanNodeSpec,
+  PlanScheduleSpec,
+  SignalDeclaration,
+} from '@lota-sdk/shared'
+
+import type { RecordIdRef } from '../db/record-id'
+
+export interface PluginContextEnricher {
+  domain: string
+  enrich(params: {
+    objective: string
+    organizationId: string
+  }): Promise<{ data: Record<string, unknown>; confidence: number }>
+}
+
 export interface LotaPluginContributions {
   envKeys: readonly string[]
   schemaFiles: readonly (string | URL)[]
+  signals?: readonly SignalDeclaration[]
+}
+
+export interface PluginNodeExecutorContext {
+  organizationId: string
+  workstreamId: string
+  planId: string
+  nodeId: string
+  userId?: RecordIdRef
+  userName?: string
+}
+
+export interface PluginNodeExecutionParams {
+  operation: string
+  nodeSpec: PlanNodeSpec
+  inputs: Record<string, unknown>
+  context: PluginNodeExecutorContext
+}
+
+export interface PluginNodeExecutor {
+  supportedOperations: readonly string[]
+  executeNode(params: PluginNodeExecutionParams): Promise<PlanNodeResult>
+}
+
+export interface SystemNodeExecutor {
+  supportedOperations: readonly string[]
+  executeNode(params: PluginNodeExecutionParams): Promise<PlanNodeResult>
+}
+
+export interface PlaybookContribution {
+  name: string
+  description: string
+  tags: string[]
+  draft: PlanDraft
+  schedule?: PlanScheduleSpec
+  cycleSchedule?: CycleSchedule
+  carryForwardPolicy?: CarryForwardPolicy
+}
+
+export interface PlaybookContributor {
+  playbooks: readonly PlaybookContribution[]
+}
+
+export interface PluginDomainAgentDefinition {
+  agentId: string
+  displayName: string
+  capabilities: readonly string[]
 }
 
 export interface LotaPlugin<TServices = Record<string, unknown>, TTools = Record<string, unknown>> {
   services: TServices
+  nodeExecutor?: PluginNodeExecutor
   tools?: TTools
   contributions: LotaPluginContributions
+  playbookContributor?: PlaybookContributor
+  domainAgents?: readonly PluginDomainAgentDefinition[]
+  contextEnrichers?: readonly PluginContextEnricher[]
+  onSignal?: (signal: string, payload: unknown, source: string) => Promise<void> | void
 }

package/src/runtime/retrieval-adapters.ts

@@ -11,7 +11,7 @@ interface ScopedRetrievalResult<TCandidate> {
 export async function executeScopedRetrieval<TCandidate>(
   tasks: ScopedRetrievalTask<TCandidate>[],
 ): Promise<ScopedRetrievalResult<TCandidate>[]> {
-  return await Promise.all(tasks.map(async (task) => ({ scopeTag: task.scopeTag, candidates: await task.retrieve() })))
+  return Promise.all(tasks.map(async (task) => ({ scopeTag: task.scopeTag, candidates: await task.retrieve() })))
 }
 
 export function countScopedRetrievalCandidates<TCandidate>(scoped: ScopedRetrievalResult<TCandidate>[]): number {