@lota-sdk/core 0.4.7 → 0.4.9

package/src/runtime/{context-compaction.ts → context-compaction/context-compaction.ts}

@@ -1,7 +1,15 @@
 import type { ChatMessage } from '@lota-sdk/shared'
+import { Schema, Effect } from 'effect'
 import { z } from 'zod'
 
-import { CHARS_PER_TOKEN_ESTIMATE, compactWhitespace, readRecord, readString, stringifyUnknown } from '../utils/string'
+import { nowEpochMillis } from '../../utils/date-time'
+import {
+  CHARS_PER_TOKEN_ESTIMATE,
+  compactWhitespace,
+  readRecord,
+  readString,
+  stringifyUnknown,
+} from '../../utils/string'
 import {
   COMPACTION_CHUNK_MAX_CHARS,
   CONTEXT_COMPACTION_INCLUDED_TOOL_NAMES,
@@ -51,6 +59,11 @@ export interface ContextCompactionRunnerParams {
   transcript: string
 }
 
+class CompactionError extends Schema.TaggedErrorClass<CompactionError>()('CompactionError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
 export interface ContextCompactionPromptParams {
   previousSummary: string
   transcript: string
@@ -216,8 +229,8 @@ export function buildMemoryBlockCompactionPrompt(params: MemoryBlockCompactionPr
 export function createContextCompactionRuntime(
   options: CreateContextCompactionRuntimeOptions,
 ): ContextCompactionRuntime {
-  const now = options.now ?? (() => Date.now())
-  const randomId = options.randomId ?? (() => crypto.randomUUID())
+  const now = options.now ?? nowEpochMillis
+  const randomId = options.randomId ?? (() => Bun.randomUUIDv7())
   const thresholdRatio = options.thresholdRatio ?? CONTEXT_COMPACTION_THRESHOLD_RATIO
   const outputReserveTokens = options.outputReserveTokens ?? CONTEXT_OUTPUT_RESERVE_TOKENS
   const safetyMarginTokens = options.safetyMarginTokens ?? CONTEXT_SAFETY_MARGIN_TOKENS
@@ -312,111 +325,121 @@ export function createContextCompactionRuntime(
     return { estimatedTokens, threshold, shouldCompact: estimatedTokens >= threshold }
   }
 
-  const compactContextMessages = async (params: {
-    previousSummary: string
-    newMessages: ContextMessage[]
-  }): Promise<CompactionOutput> => {
-    const chunks = splitByCharBudget(params.newMessages, compactionChunkMaxChars)
-    let summary = normalizeSummary(params.previousSummary)
-
-    for (const chunk of chunks) {
-      const transcript = toCompactionTranscript(chunk)
-      const output = await options.runCompacter({ previousSummary: summary, chunk, transcript })
-      summary = normalizeSummary(output.summary)
-    }
-
-    return { summary }
-  }
-
-  const rollupSummaryIfOversized = async (summary: string): Promise<string> => {
-    if (estimateTokens(summary) <= summaryRollupMaxTokens) {
-      return summary
-    }
+  const compactContextMessagesEffect = (params: { previousSummary: string; newMessages: ContextMessage[] }) =>
+    Effect.gen(function* () {
+      const chunks = splitByCharBudget(params.newMessages, compactionChunkMaxChars)
+      let summary = normalizeSummary(params.previousSummary)
+
+      for (const chunk of chunks) {
+        const transcript = toCompactionTranscript(chunk)
+        const output = yield* Effect.tryPromise({
+          try: () => options.runCompacter({ previousSummary: summary, chunk, transcript }),
+          catch: (error: unknown) => new CompactionError({ message: String(error), cause: error }),
+        })
+        summary = normalizeSummary(output.summary)
+      }
 
-    const output = await compactContextMessages({
-      previousSummary: '',
-      newMessages: [{ role: 'assistant', text: summary, sourceMessageId: 'summary-rollup' }],
+      return { summary }
     })
 
-    return normalizeSummary(output.summary)
-  }
-
-  const compactHistory = async (params: CompactHistoryParams): Promise<CompactHistoryResult> => {
-    let summaryText = normalizeSummary(params.summaryText)
-    let remainingMessages = [...params.liveMessages]
-    let compactedMessages: ChatMessage[] = []
-    let lastCompactedMessageId: string | undefined
-    const summaryPayload = buildSyntheticSummaryPayload(summaryText)
-    const initialPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
-    const inputChars = initialPayload.length
-
-    const buildEarlyExitResult = (estimatedTokens: number): CompactHistoryResult => {
-      const exitSummaryPayload = buildSyntheticSummaryPayload(summaryText)
-      const outputPayload = JSON.stringify([...(exitSummaryPayload ? [exitSummaryPayload] : []), ...remainingMessages])
-      return {
-        compacted: compactedMessages.length > 0,
-        summaryText,
-        ...(lastCompactedMessageId ? { lastCompactedMessageId } : {}),
-        compactedMessages,
-        compactedMessageCount: compactedMessages.length,
-        remainingMessageCount: remainingMessages.length,
-        estimatedTokens,
-        inputChars,
-        outputChars: outputPayload.length,
+  const rollupSummaryIfOversizedEffect = (summary: string) =>
+    Effect.gen(function* () {
+      if (estimateTokens(summary) <= summaryRollupMaxTokens) {
+        return summary
       }
-    }
 
-    for (;;) {
-      const assessment = shouldCompactHistory({
-        summaryText,
-        liveMessages: remainingMessages,
-        contextSize: params.contextSize,
+      const output = yield* compactContextMessagesEffect({
+        previousSummary: '',
+        newMessages: [{ role: 'assistant', text: summary, sourceMessageId: 'summary-rollup' }],
       })
 
-      if (!assessment.shouldCompact) {
-        return buildEarlyExitResult(assessment.estimatedTokens)
-      }
+      return normalizeSummary(output.summary)
+    })
 
-      const boundary = Math.max(0, remainingMessages.length - params.tailMessageCount)
-      if (boundary <= 0) {
-        return buildEarlyExitResult(assessment.estimatedTokens)
+  const compactHistoryEffect = (params: CompactHistoryParams) =>
+    Effect.gen(function* () {
+      let summaryText = normalizeSummary(params.summaryText)
+      let remainingMessages = [...params.liveMessages]
+      let compactedMessages: ChatMessage[] = []
+      let lastCompactedMessageId: string | undefined
+      const summaryPayload = buildSyntheticSummaryPayload(summaryText)
+      const initialPayload = stringifyUnknown([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages]) ?? ''
+      const inputChars = initialPayload.length
+
+      const buildEarlyExitResult = (estimatedTokens: number): CompactHistoryResult => {
+        const exitSummaryPayload = buildSyntheticSummaryPayload(summaryText)
+        const outputPayload =
+          stringifyUnknown([...(exitSummaryPayload ? [exitSummaryPayload] : []), ...remainingMessages]) ?? ''
+        return {
+          compacted: compactedMessages.length > 0,
+          summaryText,
+          ...(lastCompactedMessageId ? { lastCompactedMessageId } : {}),
+          compactedMessages,
+          compactedMessageCount: compactedMessages.length,
+          remainingMessageCount: remainingMessages.length,
+          estimatedTokens,
+          inputChars,
+          outputChars: outputPayload.length,
+        }
       }
 
-      const candidatePrefix = remainingMessages.slice(0, boundary)
-      const messagesToCompact = candidatePrefix.filter((message) => !readIsCompacted(message))
-      const contextMessages = messagesToCompact
-        .map(toContextMessageFromChatMessage)
-        .filter((message) => compactWhitespace(message.text).length > 0)
-      const sourceText = toCompactionTranscript(contextMessages)
+      for (;;) {
+        const assessment = shouldCompactHistory({
+          summaryText,
+          liveMessages: remainingMessages,
+          contextSize: params.contextSize,
+        })
 
-      if (!compactWhitespace(sourceText)) {
-        return buildEarlyExitResult(assessment.estimatedTokens)
-      }
+        if (!assessment.shouldCompact) {
+          return buildEarlyExitResult(assessment.estimatedTokens)
+        }
+
+        const boundary = Math.max(0, remainingMessages.length - params.tailMessageCount)
+        if (boundary <= 0) {
+          return buildEarlyExitResult(assessment.estimatedTokens)
+        }
 
-      let nextSummary = normalizeSummary(
-        (await compactContextMessages({ previousSummary: summaryText, newMessages: contextMessages })).summary,
-      )
-      nextSummary = await rollupSummaryIfOversized(nextSummary)
+        const candidatePrefix = remainingMessages.slice(0, boundary)
+        const messagesToCompact = candidatePrefix.filter((message) => !readIsCompacted(message))
+        const contextMessages = messagesToCompact
+          .map(toContextMessageFromChatMessage)
+          .filter((message) => compactWhitespace(message.text).length > 0)
+        const sourceText = toCompactionTranscript(contextMessages)
 
-      if (nextSummary.length >= sourceText.length) {
-        throw new Error('Compaction summary is not shorter than compacted source')
-      }
+        if (!compactWhitespace(sourceText)) {
+          return buildEarlyExitResult(assessment.estimatedTokens)
+        }
 
-      summaryText = nextSummary
-      compactedMessages = [
-        ...compactedMessages,
-        ...candidatePrefix.map((message) => markMessageCompacted(message, now)),
-      ]
-      lastCompactedMessageId = candidatePrefix.at(-1)?.id ?? lastCompactedMessageId
-      remainingMessages = remainingMessages.slice(boundary)
+        let nextSummary = normalizeSummary(
+          (yield* compactContextMessagesEffect({ previousSummary: summaryText, newMessages: contextMessages })).summary,
+        )
+        nextSummary = yield* rollupSummaryIfOversizedEffect(nextSummary)
 
-      if (remainingMessages.length <= params.tailMessageCount) {
-        continue
+        if (nextSummary.length >= sourceText.length) {
+          return yield* new CompactionError({ message: 'Compaction summary is not shorter than compacted source' })
+        }
+
+        summaryText = nextSummary
+        compactedMessages = [
+          ...compactedMessages,
+          ...candidatePrefix.map((message) => markMessageCompacted(message, now)),
+        ]
+        lastCompactedMessageId = candidatePrefix.at(-1)?.id ?? lastCompactedMessageId
+        remainingMessages = remainingMessages.slice(boundary)
+
+        if (remainingMessages.length <= params.tailMessageCount) {
+          continue
+        }
       }
-    }
-  }
+    })
 
-  return { createSummaryMessage, prependSummaryMessage, estimateThreshold, shouldCompactHistory, compactHistory }
+  return {
+    createSummaryMessage,
+    prependSummaryMessage,
+    estimateThreshold,
+    shouldCompactHistory,
+    compactHistory: (params) => Effect.runPromise(compactHistoryEffect(params)),
+  }
 }
 
 export function parseCompactionOutput(value: unknown): CompactionOutput {

package/src/runtime/execution-plan-visibility.ts

@@ -1,6 +1,6 @@
 import type { PlanExecutionVisibility, PlanNodeSpecRecord, PlanSpecRecord } from '@lota-sdk/shared'
 
-import { agentRoster } from '../config/agent-defaults'
+import { isAgentName } from '../config/agent-defaults'
 
 export function resolvePlanNodeExecutionVisibility(
   plan: Pick<PlanSpecRecord, 'defaultExecutionVisibility'>,
@@ -12,7 +12,7 @@ export function resolvePlanNodeExecutionVisibility(
     return configuredVisibility
   }
 
-  return node.owner.executorType === 'agent' && agentRoster.includes(node.owner.ref) ? 'visible' : 'silent'
+  return node.owner.executorType === 'agent' && isAgentName(node.owner.ref) ? 'visible' : 'silent'
 }
 
 export function shouldPlanNodeUseVisibleTurn(

package/src/runtime/execution-plan.ts

@@ -1,4 +1,5 @@
 import type { SerializableExecutionPlan } from '@lota-sdk/shared'
+import { Schema, Duration, Effect } from 'effect'
 
 type ExecutionPlanPromptSummary = Pick<SerializableExecutionPlan, 'runId' | 'title'>
 
@@ -24,6 +25,15 @@ function formatExecutionPlansForPrompt(plans: SerializableExecutionPlan[]): stri
   return ['<execution-plan-state>', JSON.stringify(payload, null, 2), '</execution-plan-state>'].join('\n')
 }
 
+export class ExecutionPlanCacheError extends Schema.TaggedErrorClass<ExecutionPlanCacheError>()(
+  'ExecutionPlanCacheError',
+  { message: Schema.String, cause: Schema.Defect },
+) {}
+
+export function toExecutionPlanCacheError(cause: unknown): ExecutionPlanCacheError {
+  return new ExecutionPlanCacheError({ message: cause instanceof Error ? cause.message : String(cause), cause })
+}
+
 export function buildExecutionPlanInstructionSections(plans: SerializableExecutionPlan[] | null | undefined): string[] {
   const normalized = plans ?? []
   return [EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT, formatExecutionPlansForPrompt(normalized)]
@@ -31,27 +41,44 @@ export function buildExecutionPlanInstructionSections(plans: SerializableExecuti
 
 export function createExecutionPlanInstructionSectionCache(params: {
   disabled?: boolean
-  loadPlans: () => Promise<SerializableExecutionPlan[]>
+  loadPlansEffect: () => Effect.Effect<SerializableExecutionPlan[], ExecutionPlanCacheError>
 }) {
-  let plansPromise: Promise<SerializableExecutionPlan[]> | null = null
-  let sectionsPromise: Promise<string[] | undefined> | null = null
+  const [getPlansCachedEffect, invalidatePlansEffect] = Effect.runSync(
+    Effect.cachedInvalidateWithTTL(
+      Effect.suspend(() => (params.disabled ? Effect.succeed([]) : params.loadPlansEffect())),
+      Duration.infinity,
+    ),
+  )
+  const [getSectionsCachedEffect, invalidateSectionsEffect] = Effect.runSync(
+    Effect.cachedInvalidateWithTTL(
+      Effect.gen(function* () {
+        if (params.disabled) {
+          return undefined
+        }
+
+        const plans = yield* getPlansCachedEffect
+        return buildExecutionPlanInstructionSections(plans)
+      }),
+      Duration.infinity,
+    ),
+  )
+
+  const getPlansEffect = (): Effect.Effect<SerializableExecutionPlan[], ExecutionPlanCacheError> => getPlansCachedEffect
+
+  const getSectionsEffect = (): Effect.Effect<string[] | undefined, ExecutionPlanCacheError> => getSectionsCachedEffect
 
   return {
     invalidate() {
-      plansPromise = null
-      sectionsPromise = null
+      Effect.runSync(invalidatePlansEffect)
+      Effect.runSync(invalidateSectionsEffect)
     },
-    async getPlans(): Promise<SerializableExecutionPlan[]> {
-      if (params.disabled) return []
-
-      plansPromise ??= params.loadPlans()
-      return plansPromise
+    getPlansEffect,
+    getSectionsEffect,
+    getPlans() {
+      return Effect.runPromise(getPlansEffect())
     },
-    async getSections(): Promise<string[] | undefined> {
-      if (params.disabled) return undefined
-
-      sectionsPromise ??= this.getPlans().then((plans) => buildExecutionPlanInstructionSections(plans))
-      return sectionsPromise
+    getSections() {
+      return Effect.runPromise(getSectionsEffect())
     },
   }
 }

package/src/runtime/graph-designer.ts

@@ -1,15 +1,19 @@
 import type { GraphDesignRequest, GraphDesignResponse } from '@lota-sdk/shared'
+import { Effect } from 'effect'
+
+import { getOptionalCurrentRuntime } from '../effect/runtime-ref'
+import { RuntimeConfigServiceTag } from '../effect/services'
 
 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
+  const runtime = getOptionalCurrentRuntime()
+  if (!runtime) {
+    return null
+  }
+
+  const runtimeConfig = runtime.runSync(Effect.service(RuntimeConfigServiceTag))
+  return runtimeConfig.graphDesigner ?? null
 }

package/src/runtime/helper-model.ts

@@ -5,8 +5,13 @@ import type {
   ToolLoopAgentOnStepFinishCallback,
   ToolSet,
 } from 'ai'
+import { Context, Duration, Effect, Layer, Metric } from 'effect'
 import type { ZodSchema } from 'zod'
 
+import type { ValidationError } from '../effect/errors'
+import { AiGenerationError, BadRequestError } from '../effect/errors'
+import { summarizeZodIssues, toValidationError } from '../effect/zod'
+import { nowEpochMillis } from '../utils/date-time'
 import { isRecord, stringifyUnknown } from '../utils/string'
 
 export interface HelperToolLoopAgentOptions {
@@ -70,7 +75,7 @@ function isRateLimitError(error: unknown): boolean {
   return getErrorStatus(error) === 429
 }
 
-function formatError(tag: string, error: unknown): Error {
+function formatGenerationError(tag: string, error: unknown): AiGenerationError {
   const status = getErrorStatus(error)
   const rateLimited = isRateLimitError(error)
   const message = error instanceof Error ? error.message : String(error)
@@ -87,7 +92,73 @@ function formatError(tag: string, error: unknown): Error {
   if (responseBody) parts.push(`response_body=${responseBody}`)
   if (requestUrl) parts.push(`url=${requestUrl}`)
 
-  return new Error(parts.join(' '))
+  return new AiGenerationError({
+    source: tag,
+    message: parts.join(' '),
+    ...(status !== null ? { status } : {}),
+    ...(rateLimited ? { rateLimited: true } : {}),
+    ...(responseData ? { providerData: responseData } : {}),
+    ...(responseBody ? { responseBody } : {}),
+    ...(requestUrl ? { url: requestUrl } : {}),
+  })
+}
+
+function emptyHelperMessagesError(tag: string): BadRequestError {
+  return new BadRequestError({ message: `[${tag}] Empty helper messages` })
+}
+
+function parseStructuredRootCandidate<T>(params: {
+  tag: string
+  schema: ZodSchema<T>
+  candidate: unknown
+}): { data: T } | { error: ValidationError } {
+  const directParsed = params.schema.safeParse(params.candidate)
+  if (directParsed.success) {
+    return { data: directParsed.data }
+  }
+
+  return {
+    error: toValidationError(
+      directParsed.error,
+      `[${params.tag}] Structured output failed schema validation: ${summarizeZodIssues(directParsed.error.issues)}`,
+    ),
+  }
+}
+
+function createHelperAgent(params: {
+  tag: string
+  createAgent: CreateHelperAgentFn
+  systemPrompt?: string
+  temperature?: number
+  maxOutputTokens?: number
+  output?: Output.Output
+}): Effect.Effect<HelperAgent, AiGenerationError> {
+  return Effect.try({
+    try: () =>
+      params.createAgent({
+        ...(params.systemPrompt ? { instructions: params.systemPrompt } : {}),
+        ...(params.output ? { output: params.output } : {}),
+        ...(typeof params.temperature === 'number' ? { temperature: params.temperature } : {}),
+        ...(typeof params.maxOutputTokens === 'number' ? { maxOutputTokens: params.maxOutputTokens } : {}),
+        maxRetries: 2,
+      }),
+    catch: (error) => formatGenerationError(params.tag, error),
+  })
+}
+
+function generateWithHelperAgent(
+  tag: string,
+  agent: HelperAgent,
+  params: { messages: HelperMessage[]; timeoutMs?: number },
+): Effect.Effect<{ text?: unknown; output?: unknown }, AiGenerationError> {
+  return Effect.tryPromise({
+    try: () =>
+      agent.generate({
+        messages: toModelMessages(params.messages),
+        ...(typeof params.timeoutMs === 'number' ? { timeout: params.timeoutMs } : {}),
+      }),
+    catch: (error) => formatGenerationError(tag, error),
+  })
 }
 
 function toModelMessages(messages: HelperMessage[]): Array<{ role: 'user' | 'assistant'; content: string }> {
@@ -118,13 +189,6 @@ function resolveStructuredSystemPrompt(systemPrompt?: string): string {
   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('; ')
-}
-
 function parseStructuredCandidate<T>(params: {
   schema: ZodSchema<T>
   candidate: unknown
@@ -147,40 +211,54 @@ function parseStructuredCandidate<T>(params: {
   return null
 }
 
+const helperModelDuration = Metric.timer('helper_model_duration')
+
+function recordHelperModelDuration(tag: string, startedAt: number): Effect.Effect<void, never, never> {
+  return Metric.update(
+    Metric.withAttributes(helperModelDuration, { tag }),
+    Duration.millis(Math.max(0, nowEpochMillis() - startedAt)),
+  )
+}
+
 export function createHelperModelRuntime() {
-  async function generateHelperText(params: GenerateHelperTextParams): Promise<string> {
+  function generateHelperTextEffect(
+    params: GenerateHelperTextParams,
+  ): Effect.Effect<string, AiGenerationError | BadRequestError | ValidationError> {
     const systemPrompt = resolveSystemPrompt({
       explicitSystemPrompt: params.systemPrompt,
       defaultSystemPrompt: params.defaultSystemPrompt,
     })
 
     if (!systemPrompt && params.messages.length === 0) {
-      throw new Error(`[${params.tag}] Empty helper messages`)
+      return Effect.fail(emptyHelperMessagesError(params.tag))
     }
 
-    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 startedAt = nowEpochMillis()
 
-      const result = await agent.generate({
-        messages: toModelMessages(params.messages),
-        ...(typeof params.timeoutMs === 'number' ? { timeout: params.timeoutMs } : {}),
+    return Effect.gen(function* () {
+      const agent = yield* createHelperAgent({
+        tag: params.tag,
+        createAgent: params.createAgent,
+        systemPrompt,
+        temperature: params.temperature,
+        maxOutputTokens: params.maxOutputTokens,
       })
+      const result = yield* generateWithHelperAgent(params.tag, agent, params)
       const text = typeof result.text === 'string' ? result.text.trim() : ''
       if (!text) {
-        throw new Error('Empty helper model output')
+        return yield* formatGenerationError(params.tag, new Error('Empty helper model output'))
       }
       return text
-    } catch (error) {
-      throw formatError(params.tag, error)
-    }
+    }).pipe(Effect.ensuring(recordHelperModelDuration(params.tag, startedAt)))
   }
 
-  async function generateHelperStructured<T>(params: GenerateHelperStructuredParams<T>): Promise<T> {
+  function generateHelperText(params: GenerateHelperTextParams): Promise<string> {
+    return Effect.runPromise(generateHelperTextEffect(params))
+  }
+
+  function generateHelperStructuredEffect<T>(
+    params: GenerateHelperStructuredParams<T>,
+  ): Effect.Effect<T, AiGenerationError | BadRequestError | ValidationError> {
     const baseSystemPrompt = resolveSystemPrompt({
       explicitSystemPrompt: params.systemPrompt,
       defaultSystemPrompt: params.defaultSystemPrompt,
@@ -188,39 +266,48 @@ export function createHelperModelRuntime() {
     const systemPrompt = resolveStructuredSystemPrompt(baseSystemPrompt)
 
     if (!baseSystemPrompt && params.messages.length === 0) {
-      throw new Error(`[${params.tag}] Empty helper messages`)
+      return Effect.fail(emptyHelperMessagesError(params.tag))
     }
 
-    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 startedAt = nowEpochMillis()
 
-      const result = await agent.generate({
-        messages: toModelMessages(params.messages),
-        ...(typeof params.timeoutMs === 'number' ? { timeout: params.timeoutMs } : {}),
+    return Effect.gen(function* () {
+      const agent = yield* createHelperAgent({
+        tag: params.tag,
+        createAgent: params.createAgent,
+        systemPrompt,
+        temperature: params.temperature,
+        maxOutputTokens: params.maxOutputTokens,
+        output: Output.object({ schema: params.schema }),
       })
+      const result = yield* generateWithHelperAgent(params.tag, agent, params)
       const parsed = parseStructuredCandidate({ schema: params.schema, candidate: result.output })
       if (parsed) {
         return parsed.data
       }
 
-      const directParsed = params.schema.safeParse(result.output)
-      if (!directParsed.success) {
-        throw new Error(
-          `Structured output failed schema validation: ${formatSchemaIssueSummary(directParsed.error.issues)}`,
-        )
+      const validated = parseStructuredRootCandidate({
+        tag: params.tag,
+        schema: params.schema,
+        candidate: result.output,
+      })
+      if ('error' in validated) {
+        return yield* validated.error
       }
 
-      return directParsed.data
-    } catch (error) {
-      throw formatError(params.tag, error)
-    }
+      return validated.data
+    }).pipe(Effect.ensuring(recordHelperModelDuration(params.tag, startedAt)))
+  }
+
+  function generateHelperStructured<T>(params: GenerateHelperStructuredParams<T>): Promise<T> {
+    return Effect.runPromise(generateHelperStructuredEffect(params))
   }
 
-  return { generateHelperText, generateHelperStructured }
+  return { generateHelperTextEffect, generateHelperText, generateHelperStructuredEffect, generateHelperStructured }
 }
+
+export type HelperModelRuntime = ReturnType<typeof createHelperModelRuntime>
+
+export class HelperModelTag extends Context.Service<HelperModelTag, HelperModelRuntime>()('HelperModel') {}
+
+export const HelperModelLive = Layer.succeed(HelperModelTag, createHelperModelRuntime())

package/src/runtime/index.ts

@@ -4,15 +4,15 @@ export * from './agent-stream-helpers'
 export * from './agent-types'
 export * from './chat-request-routing'
 export * from './chat-run-registry'
-export * from './context-compaction'
+export * from './context-compaction/context-compaction'
 export * from './execution-plan'
 export * from './graph-designer'
 export * from './helper-model'
 export * from './indexed-repositories-policy'
 export * from './instruction-sections'
-export * from './memory-block'
-export * from './memory-digest-policy'
-export * from './memory-scope'
+export * from './memory/memory-block'
+export * from './memory/memory-digest-policy'
+export * from './memory/memory-scope'
 export * from './llm-content'
 export * from './plugin-resolution'
 export * from './plugin-types'
@@ -20,8 +20,8 @@ export * from './runtime-config'
 export * from './runtime-extensions'
 export * from './runtime-worker-registry'
 export * from './skill-extraction-policy'
-export * from './social-chat'
-export * from './team-consultation-orchestrator'
-export * from './team-consultation-prompts'
+export * from './social-chat/social-chat'
+export * from './team-consultation/team-consultation-orchestrator'
+export * from './team-consultation/team-consultation-prompts'
 export * from './turn-lifecycle'
 export * from './thread-chat-helpers'