@lota-sdk/core 0.1.5

package/src/runtime/execution-plan.ts

@@ -0,0 +1,59 @@
+import type { SerializableExecutionPlan } from '@lota-sdk/shared/schemas/execution-plan'
+
+export const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
+- Before doing multi-step work, create an execution plan instead of tracking steps only in prose.
+- Keep plans short and operational. Prefer 2 to 7 tasks unless the work truly needs more.
+- Use execution-plan tools to create, replace, update, inspect, and restart the plan.
+- Only one execution-plan task may be active at a time.
+- Every task should have a concrete rationale and a concise output summary when work happens.
+- Treat prior task output summaries and carried tasks in <execution-plan-state> as observed facts.
+- If the ordered steps materially change, replace the plan instead of silently rewriting it in prose.
+- If the active plan is blocked, do not continue blindly. Replan, restart a task, ask for user input, or abort.
+</execution-plan-protocol>`
+
+export function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | undefined): string | undefined {
+  if (!plan) return undefined
+
+  const payload = {
+    policy: {
+      activePlanIsAuthoritative: true,
+      priorOutputSummariesAreObservedFacts: true,
+      singleActiveTask: true,
+      explicitReplanRequired: true,
+      failureBudget: 2,
+    },
+    plan,
+  }
+
+  return ['<execution-plan-state>', JSON.stringify(payload, null, 2), '</execution-plan-state>'].join('\n')
+}
+
+export function buildExecutionPlanInstructionSections(
+  plan: SerializableExecutionPlan | null | undefined,
+): string[] | undefined {
+  const sections = [EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT]
+  const executionPlanStateSection = formatExecutionPlanForPrompt(plan)
+  if (executionPlanStateSection) {
+    sections.push(executionPlanStateSection)
+  }
+  return sections
+}
+
+export function createExecutionPlanInstructionSectionCache(params: {
+  disabled?: boolean
+  loadPlan: () => Promise<SerializableExecutionPlan | null | undefined>
+}) {
+  let sectionsPromise: Promise<string[] | undefined> | null = null
+
+  return {
+    invalidate() {
+      sectionsPromise = null
+    },
+    async getSections(): Promise<string[] | undefined> {
+      if (params.disabled) return undefined
+
+      sectionsPromise ??= params.loadPlan().then((plan) => buildExecutionPlanInstructionSections(plan))
+      return await sectionsPromise
+    },
+  }
+}

package/src/runtime/helper-model.ts

@@ -0,0 +1,405 @@
+import { Output } from 'ai'
+import type {
+  TimeoutConfiguration,
+  ToolLoopAgentOnFinishCallback,
+  ToolLoopAgentOnStepFinishCallback,
+  ToolSet,
+} from 'ai'
+import type { ZodSchema } from 'zod'
+
+export interface HelperToolLoopAgentOptions {
+  instructions?: string
+  maxOutputTokens?: number
+  temperature?: number
+  output?: Output.Output
+  maxRetries?: number
+}
+
+export interface HelperMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface HelperAgentGenerateParams {
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+  timeout?: TimeoutConfiguration
+  onStepFinish?: ToolLoopAgentOnStepFinishCallback<ToolSet>
+  onFinish?: ToolLoopAgentOnFinishCallback<ToolSet>
+}
+
+export interface HelperAgent {
+  generate(params: HelperAgentGenerateParams): Promise<{ text?: unknown; output?: unknown }>
+}
+
+export type CreateHelperAgentFn = (options: HelperToolLoopAgentOptions) => HelperAgent
+
+export interface GenerateHelperTextParams {
+  tag: string
+  createAgent: CreateHelperAgentFn
+  messages: HelperMessage[]
+  systemPrompt?: string
+  defaultSystemPrompt?: string
+  temperature?: number
+  maxOutputTokens?: number
+  timeoutMs?: number
+}
+
+export interface GenerateHelperStructuredParams<T> extends Omit<GenerateHelperTextParams, 'tag'> {
+  tag: string
+  schema: ZodSchema<T>
+  textFallbackParser?: (text: string) => T | null
+}
+
+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 {
+  const field = value[key]
+  if (typeof field === 'number' && Number.isFinite(field)) return field
+  if (typeof field === 'string') {
+    const parsed = Number(field)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return null
+}
+
+function getErrorStatus(error: unknown): number | null {
+  if (!isObject(error)) return null
+  return getNumericField(error, 'status') ?? getNumericField(error, 'statusCode')
+}
+
+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 = raw.replace(/\s+/g, ' ').trim()
+  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 responseBody = errorRecord ? stringifyUnknown(errorRecord.responseBody, 600) : null
+  const responseData = errorRecord ? stringifyUnknown(errorRecord.data, 600) : null
+  const requestUrl = errorRecord ? stringifyUnknown(errorRecord.url, 200) : null
+
+  const parts = [`[${tag}]`]
+  if (status !== null) parts.push(`status=${status}`)
+  if (rateLimited) parts.push('rate_limited')
+  parts.push(message)
+  if (responseData) parts.push(`provider_data=${responseData}`)
+  if (responseBody) parts.push(`response_body=${responseBody}`)
+  if (requestUrl) parts.push(`url=${requestUrl}`)
+
+  return new Error(parts.join(' '))
+}
+
+function toModelMessages(messages: HelperMessage[]): Array<{ role: 'user' | 'assistant'; content: string }> {
+  return messages
+    .filter((message): message is HelperMessage & { role: 'user' | 'assistant' } => message.role !== 'system')
+    .map((message) => ({ role: message.role, content: message.content }))
+}
+
+function resolveSystemPrompt(params: {
+  explicitSystemPrompt?: string
+  defaultSystemPrompt?: string
+}): string | undefined {
+  if (typeof params.explicitSystemPrompt === 'string') {
+    const explicit = params.explicitSystemPrompt.trim()
+    return explicit.length > 0 ? explicit : undefined
+  }
+
+  const fallback = params.defaultSystemPrompt?.trim()
+  return fallback && fallback.length > 0 ? fallback : undefined
+}
+
+function resolveStructuredSystemPrompt(systemPrompt?: string): string {
+  const parts = [
+    systemPrompt?.trim(),
+    'Return only a valid JSON object that matches the required schema. Do not wrap it in markdown or code fences.',
+  ].filter((part): part is string => Boolean(part && part.length > 0))
+
+  return parts.join('\n\n')
+}
+
+function formatSchemaIssueSummary(issues: Array<{ path: PropertyKey[]; message: string }>): string {
+  return issues
+    .slice(0, 5)
+    .map((issue) => `${issue.path.map((segment) => String(segment)).join('.') || 'root'}: ${issue.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
+}): { data: T; source: string } | null {
+  const direct = params.schema.safeParse(params.candidate)
+  if (direct.success) {
+    return { data: direct.data, source: 'root' }
+  }
+
+  if (isObject(params.candidate)) {
+    for (const key of ['output', 'result', 'data'] as const) {
+      const nested = params.candidate[key]
+      const nestedParsed = params.schema.safeParse(nested)
+      if (nestedParsed.success) {
+        return { data: nestedParsed.data, source: key }
+      }
+    }
+  }
+
+  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({
+      explicitSystemPrompt: params.systemPrompt,
+      defaultSystemPrompt: params.defaultSystemPrompt,
+    })
+
+    if (!systemPrompt && params.messages.length === 0) {
+      throw new Error(`[${params.tag}] Empty helper messages`)
+    }
+
+    try {
+      const agent = params.createAgent({
+        ...(systemPrompt ? { instructions: systemPrompt } : {}),
+        ...(typeof params.temperature === 'number' ? { temperature: params.temperature } : {}),
+        ...(typeof params.maxOutputTokens === 'number' ? { maxOutputTokens: params.maxOutputTokens } : {}),
+        maxRetries: 2,
+      })
+
+      const result = await agent.generate({
+        messages: toModelMessages(params.messages),
+        ...(typeof params.timeoutMs === 'number' ? { timeout: params.timeoutMs } : {}),
+      })
+      const text = typeof result.text === 'string' ? result.text.trim() : ''
+      if (!text) {
+        throw new Error('Empty helper model output')
+      }
+      return text
+    } catch (error) {
+      throw formatError(params.tag, error)
+    }
+  }
+
+  async function generateHelperStructured<T>(params: GenerateHelperStructuredParams<T>): Promise<T> {
+    const baseSystemPrompt = resolveSystemPrompt({
+      explicitSystemPrompt: params.systemPrompt,
+      defaultSystemPrompt: params.defaultSystemPrompt,
+    })
+    const systemPrompt = resolveStructuredSystemPrompt(baseSystemPrompt)
+
+    if (!baseSystemPrompt && params.messages.length === 0) {
+      throw new Error(`[${params.tag}] Empty helper messages`)
+    }
+
+    try {
+      const agent = params.createAgent({
+        output: Output.object({ schema: params.schema }),
+        ...(systemPrompt ? { instructions: systemPrompt } : {}),
+        ...(typeof params.temperature === 'number' ? { temperature: params.temperature } : {}),
+        ...(typeof params.maxOutputTokens === 'number' ? { maxOutputTokens: params.maxOutputTokens } : {}),
+        maxRetries: 2,
+      })
+
+      const result = await agent.generate({
+        messages: toModelMessages(params.messages),
+        ...(typeof params.timeoutMs === 'number' ? { timeout: params.timeoutMs } : {}),
+      })
+      const parsed = parseStructuredCandidate({ schema: params.schema, candidate: result.output })
+      if (parsed) {
+        return parsed.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) {
+        throw new Error(
+          `Structured output failed schema validation: ${formatSchemaIssueSummary(fallbackParsed.error.issues)}`,
+        )
+      }
+
+      return fallbackParsed.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(' | ')}`)
+    }
+  }
+
+  return { generateHelperText, generateHelperStructured }
+}
+
+export const llmHelperService = createHelperModelRuntime()

package/src/runtime/indexed-repositories-policy.ts

@@ -0,0 +1,28 @@
+export type IndexedRepoAgentName = string
+
+export const REPO_SECTION_NAMES = [
+  'metadata',
+  'vision',
+  'prd',
+  'technicalMap',
+  'goToMarket',
+  'structure',
+  'summary',
+] as const
+export type RepoSectionName = (typeof REPO_SECTION_NAMES)[number]
+
+const ALL_REPO_SECTIONS: RepoSectionName[] = [...REPO_SECTION_NAMES]
+
+export const DEFAULT_REPO_SECTIONS_BY_AGENT: Record<IndexedRepoAgentName, RepoSectionName[]> = {
+  chief: [...ALL_REPO_SECTIONS],
+  ceo: [...ALL_REPO_SECTIONS],
+  cto: [...ALL_REPO_SECTIONS],
+  cpo: [...ALL_REPO_SECTIONS],
+  cmo: [...ALL_REPO_SECTIONS],
+  cfo: [...ALL_REPO_SECTIONS],
+  mentor: [...ALL_REPO_SECTIONS],
+}
+
+export function emptyAgentContextMap(): Record<IndexedRepoAgentName, string> {
+  return { chief: '', ceo: '', cto: '', cpo: '', cmo: '', cfo: '', mentor: '' }
+}

package/src/runtime/instruction-sections.ts

@@ -0,0 +1,8 @@
+export function mergeInstructionSections(...groups: Array<readonly string[] | undefined>): string[] | undefined {
+  const sections = groups
+    .flatMap((group) => group ?? [])
+    .map((section) => section.trim())
+    .filter((section) => section.length > 0)
+
+  return sections.length > 0 ? sections : undefined
+}

package/src/runtime/llm-content.ts

@@ -0,0 +1,71 @@
+export function stripMemr3Sections(text: string): string {
+  const normalized = text.replace(/\r\n/g, '\n')
+  const answerMatch = normalized.match(/\[ANSWER\]\s*\n([\s\S]*)/i)
+
+  if (answerMatch) {
+    return answerMatch[1]?.trim() ?? ''
+  }
+
+  return normalized
+    .replace(/```evidence\s*\n[\s\S]*?```/gi, '')
+    .replace(/```gaps\s*\n[\s\S]*?```/gi, '')
+    .replace(/\[EVIDENCE\][\s\S]*?(?=\n\[GAPS\]|\n\[ANSWER\]|\n*$)/i, '')
+    .replace(/\[GAPS\][\s\S]*?(?=\n\[ANSWER\]|\n*$)/i, '')
+    .replace(/\[ANSWER\]/i, '')
+    .trim()
+}
+
+const userQuestionTagsRegex = /<\/?user_question>/gi
+
+export function stripUserQuestionTags(text: string): string {
+  return text.replace(userQuestionTagsRegex, '').trim()
+}
+
+const assistantMessageTagsRegex = /<\/?assistant-message\b[^>]*>/gi
+
+export function stripAssistantMessageTags(text: string): string {
+  return text.replace(assistantMessageTagsRegex, '').trim()
+}
+
+const memorySectionsTokenRegex = /"sections"\s*:\s*\[/i
+const memoryIdTokenRegex = /"id"\s*:\s*"memory:[^"]+"/i
+const decisionHeadingRegex = /decision\s*:/i
+
+function looksLikeMemoryJsonPreamble(text: string): boolean {
+  return memorySectionsTokenRegex.test(text) && memoryIdTokenRegex.test(text)
+}
+
+function getDecisionHeadingStart(text: string): number | null {
+  const match = decisionHeadingRegex.exec(text)
+  if (!match) return null
+  return match.index
+}
+
+export function stripLeadingMemorySectionJsonBlocks(text: string): string {
+  const trimmedStart = text.trimStart()
+  if (!trimmedStart) return trimmedStart
+
+  const decisionStart = getDecisionHeadingStart(trimmedStart)
+  if (decisionStart === null) {
+    return looksLikeMemoryJsonPreamble(trimmedStart) ? '' : trimmedStart
+  }
+
+  if (decisionStart === 0) {
+    return trimmedStart
+  }
+
+  const preamble = trimmedStart.slice(0, decisionStart).trim()
+  if (!preamble || !looksLikeMemoryJsonPreamble(preamble)) {
+    return trimmedStart
+  }
+
+  return trimmedStart.slice(decisionStart).trimStart()
+}
+
+export function sanitizeAgentOutputForMemory(text: string): string {
+  const withoutAssistantTags = stripAssistantMessageTags(text)
+  const withoutMemr3 = stripMemr3Sections(withoutAssistantTags)
+  const withoutUserQuestion = stripUserQuestionTags(withoutMemr3)
+  const withoutMemoryJson = stripLeadingMemorySectionJsonBlocks(withoutUserQuestion)
+  return withoutMemoryJson.trim()
+}