Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { createHash, randomUUID } from 'node:crypto'
import { type LlmProviderId, isLlmProviderId } from '@clerum/llm-providers'
import {
type AgentStepResult,
ConfigLoader,
McpHostClient,
SignalPoller,
StatusReporter,
type StepContext,
StepCoordinator,
type StepExecutor,
type StepMcpServerRef,
type StepSpec,
type WorkflowConfig,
type WorkflowPhase,
type WorkflowRecipeSpec,
computeBackoff,
renderPrompt,
requestModelInjection,
withRetry,
} from '@clerum/workflow-runtime-core'
import { workflowStepDurationSeconds, workflowStepTotal } from '../metrics'
import { GfsPublishCancelledError, publishWorkflowOutputsToGfs } from './gfsOutputPublisher'
import { workflowStepNeedsMcpHost, workflowStepUsesSnippetRunner } from './runtimePlan'
import { SNIPPET_RUN_KEYS } from './snippetRunSchema'
import { SnippetRunnerClient } from './snippetRunnerClient'
import type { SnippetExecuteResponse } from './snippetTypes'
// NOTE: this type accepts every LlmProviderId (incl. `bedrock`), but the
// WorkflowRecipe CRD admission excludes `bedrock` from spec.agent.provider —
// the WRC configure transport is mono-credential and cannot deliver Bedrock's
// key pair (mirror of the enum comment in charts/.../workflowrecipe.yaml).
type AgentProvider = LlmProviderId
const DEFAULT_STEP_TIMEOUT_SECONDS = 300
const PROVIDER_OUTPUT_LENGTH_EXCEEDED = 'provider_output_length_exceeded'
const MCP_HOST_NOT_READY = 'mcp_host not ready'
interface RuntimeAgentSpec {
provider: AgentProvider
model: string
soul?: string
}
interface ApprovalSpec {
target: { userId?: string; teamId?: string }
message: string
timeoutSeconds?: number
}
interface RuntimeStepSpec extends Omit<StepSpec, 'agent' | 'mcpServers'> {
agent?: Partial<RuntimeAgentSpec>
mcpServers?: StepMcpServerRef[]
allowedTools?: { include?: string[] }
toolChoice?: 'auto' | 'none' | 'required'
maxRetries?: number
maxIterations?: number
requiresApproval?: ApprovalSpec
}
interface RuntimeWorkflowSpec extends Omit<WorkflowRecipeSpec, 'steps' | 'agent'> {
steps: RuntimeStepSpec[]
agent?: RuntimeAgentSpec
gfs?: {
publishTargets?: Array<{ drive: string; target: string }>
}
}
type UnknownObject = Record<string, unknown>
type RuntimeRunSpec = NonNullable<RuntimeStepSpec['run']>
type SnippetRuntimeRunSpec = Extract<RuntimeRunSpec, { type: 'snippet' }>
type SnippetRuntimeStepSpec = RuntimeStepSpec & { run: SnippetRuntimeRunSpec }
interface RuntimeStatusSnapshot {
workflowPhase: string
steps: Array<{ id: string; phase: string; output?: unknown; modelUsed?: string }>
startedAt?: string
}
export interface RuntimeDependencies {
config: WorkflowConfig
spec: RuntimeWorkflowSpec
coordinator: StepCoordinator
status: StatusReporter
signals: SignalPoller
mcpHost?: McpHostClient | null
snippetRunner?: SnippetRunnerClient | null
modelInjection?: typeof requestModelInjection
waitForMcpHost?: boolean
mcpHostReadyAttempts?: number
mcpHostReadyDelayMs?: number
}
export interface RuntimeResult {
exitCode: number
workflowPhase: WorkflowPhase
failureReason?: string
}
class StepRuntimeError extends Error {
constructor(
readonly stepId: string,
message: string
) {
super(message)
}
}
class McpHostReadinessTimeoutError extends Error {
constructor() {
super(MCP_HOST_NOT_READY)
}
}
export async function runWorkflowFromEnvironment(): Promise<RuntimeResult> {
const loader = new ConfigLoader()
const config = loader.getConfig()
const spec = parseRuntimeWorkflowSpec(await loader.getSpec())
const coordinator = new StepCoordinator()
const signals = new SignalPoller({
wrcUrl: config.wrcUrl,
workflowName: config.workflowName,
tokenProvider: config.tokenProvider,
intervalMs: config.signalPollIntervalMs,
})
const status = new StatusReporter({
wrcUrl: config.wrcUrl,
workflowName: config.workflowName,
tokenProvider: config.tokenProvider,
})
const mcpHost =
config.mcpHostUrl && config.tokenProvider.getMcpHostToken
? new McpHostClient(config.mcpHostUrl, config.tokenProvider)
: null
const snippetRunner =
config.snippetRunnerUrl && config.tokenProvider.getSnippetRunnerToken
? new SnippetRunnerClient(config.snippetRunnerUrl, config.tokenProvider)
: null
return runWorkflowRuntime({
config,
spec,
coordinator,
status,
signals,
mcpHost,
snippetRunner,
modelInjection: requestModelInjection,
})
}
export async function runWorkflowRuntime(deps: RuntimeDependencies): Promise<RuntimeResult> {
const {
config,
spec,
coordinator,
status,
signals,
mcpHost,
snippetRunner,
modelInjection = requestModelInjection,
} = deps
const stopPolling = signals.pollSignals(signal => coordinator.injectSignal(signal))
const coordinatorSpec = toCoordinatorWorkflowSpec(spec)
const runtimeStepsById = new Map(spec.steps.map(step => [step.id, step]))
const orderedSteps = coordinator.resolveOrder(coordinatorSpec.steps)
const customCoordinator =
typeof spec.coordinatorImage === 'string' && spec.coordinatorImage.trim() !== ''
const needsMcpHost = orderedSteps.some(step =>
workflowStepNeedsMcpHost(runtimeStepsById.get(step.id) ?? step, {
customCoordinator,
hasWorkflowAgent: Boolean(spec.agent),
})
)
const needsSnippetRunner = spec.steps.some(step => workflowStepUsesSnippetRunner(step))
try {
if (needsMcpHost) {
if (!mcpHost) {
throw new Error('mcp_host endpoint and token are required for agentic workflow steps')
}
if (deps.waitForMcpHost !== false) {
await waitForMcpHostReady(
mcpHost,
deps.mcpHostReadyAttempts ?? 120,
deps.mcpHostReadyDelayMs ?? 2000
)
}
}
if (needsSnippetRunner && !snippetRunner) {
throw new Error('snippet runner endpoint and token are required for snippet workflow steps')
}
const currentStatus = await readCurrentStatus(status)
const completedStepIds = new Set(
(currentStatus.steps ?? []).filter(step => step.phase === 'completed').map(step => step.id)
)
const initialOutputs = Object.fromEntries(
(currentStatus.steps ?? [])
.filter(step => step.phase === 'completed' && step.output !== undefined)
.map(step => [step.id, step.output])
)
if (orderedSteps.every(step => completedStepIds.has(step.id))) {
await status.reportWorkflowStatus('completed', { completedAt: new Date().toISOString() })
return { exitCode: 0, workflowPhase: 'completed' }
}
await status.reportWorkflowStatus('running')
let currentAgent = resolveLastCompletedAgent(orderedSteps, currentStatus, spec.agent)
let needsInitialModelInjection = true
const workflowStartedAt = currentStatus.startedAt ?? new Date().toISOString()
const workflowRunId = process.env.CLERUM_WORKFLOW_RUN_ID?.trim()
if (needsMcpHost && !workflowRunId) {
throw new Error('CLERUM_WORKFLOW_RUN_ID is required for agentic workflow usage attribution')
}
const workflowTeamId = process.env.CLERUM_WORKFLOW_TEAM_ID?.trim()
const workflowUserId = process.env.CLERUM_WORKFLOW_USER_ID?.trim()
const workflowExecutionId = workflowRunId
? `${workflowRunId}:${config.workflowName}:${workflowStartedAt}`
: ''
const executor: StepExecutor = async (step, context) => {
const runtimeStep = runtimeStepsById.get(step.id)
if (!runtimeStep) throw new StepRuntimeError(step.id, 'runtime-step-not-found')
const startedAt = new Date().toISOString()
const startedMs = Date.now()
const executorKind = resolveExecutorKind(runtimeStep)
const approvalBindingProof = runtimeStep.requiresApproval ? randomUUID() : undefined
await status.reportStepStatus(runtimeStep.id, 'running', {
executor: executorKind,
startedAt,
...(approvalBindingProof
? {
approvalBindingSha256: createHash('sha256')
.update(approvalBindingProof)
.digest('hex'),
}
: {}),
})
try {
if (isSnippetRuntimeStep(runtimeStep)) {
const output = await executeSnippetStepWithRetry(
runtimeStep,
context,
spec,
config,
snippetRunner!
)
await status.reportStepStatus(runtimeStep.id, 'completed', {
output: stringifyOutput(output),
executor: 'snippet',
durationMs: Date.now() - startedMs,
completedAt: new Date().toISOString(),
})
recordStepMetrics(runtimeStep, 'succeeded', Date.now() - startedMs)
return output
}
const stepAgent = resolveStepAgent(runtimeStep, spec.agent, currentAgent)
if (!stepAgent) {
throw new Error('agent-config-missing')
}
if (
needsInitialModelInjection ||
!currentAgent ||
stepAgent.provider !== currentAgent.provider ||
stepAgent.model !== currentAgent.model
) {
await modelInjection(config.wrcUrl, config.workflowName, config.tokenProvider, {
stepId: runtimeStep.id,
provider: stepAgent.provider,
model: stepAgent.model,
})
currentAgent = { provider: stepAgent.provider, model: stepAgent.model }
needsInitialModelInjection = false
}
const instruction = renderPrompt(runtimeStep.instruction ?? '', {
step,
previousOutputs: context.previousOutputs,
workflowName: config.workflowName,
})
const result = await executeAgenticStepWithRetry(
mcpHost!,
runtimeStep,
instruction,
{
workflowExecutionId,
...(workflowTeamId ? { workflowTeamId } : {}),
...(workflowUserId ? { workflowUserId } : {}),
},
approvalBindingProof
)
await status.reportStepStatus(runtimeStep.id, 'completed', {
output: result.output,
executor: 'agentic',
toolsCalled: result.toolsCalled,
modelUsed: `${stepAgent.provider}/${stepAgent.model}`,
durationMs: result.durationMs,
completedAt: result.completedAt ?? new Date().toISOString(),
})
recordStepMetrics(runtimeStep, 'succeeded', Date.now() - startedMs)
return result.output ?? ''
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
recordStepMetrics(runtimeStep, 'failed', Date.now() - startedMs)
throw new StepRuntimeError(runtimeStep.id, message)
}
}
const finalOutputs = await coordinator.runWorkflow(coordinatorSpec, executor, {
initialOutputs,
completedStepIds,
})
if (signals.hasSignal('cancel')) {
await status.reportWorkflowStatus('cancelled')
return { exitCode: 1, workflowPhase: 'cancelled' }
}
await publishWorkflowOutputsToGfs(spec, config, finalOutputs, {
isCancelled: () => signals.hasSignal('cancel'),
})
await status.reportWorkflowStatus('completed', { completedAt: new Date().toISOString() })
return { exitCode: 0, workflowPhase: 'completed' }
} catch (err) {
if (err instanceof GfsPublishCancelledError) {
await status.reportWorkflowStatus('cancelled')
return { exitCode: 1, workflowPhase: 'cancelled' }
}
const failureReason = err instanceof Error ? err.message : String(err)
const failedStepId = err instanceof StepRuntimeError ? err.stepId : undefined
if (failedStepId) {
await status.reportStepStatus(failedStepId, 'failed', {
failureReason,
completedAt: new Date().toISOString(),
})
await reportRemainingAsSkipped(orderedSteps, failedStepId, status)
}
if (err instanceof McpHostReadinessTimeoutError) {
await status.reportWorkflowStatus('recovering', { failureReason })
return { exitCode: 1, workflowPhase: 'recovering', failureReason }
}
await status.reportWorkflowStatus('failed', { failureReason })
return { exitCode: 1, workflowPhase: 'failed', failureReason }
} finally {
stopPolling()
}
}
async function executeSnippetStepWithRetry(
step: SnippetRuntimeStepSpec,
context: StepContext,
spec: RuntimeWorkflowSpec,
config: WorkflowConfig,
snippetRunner: SnippetRunnerClient
): Promise<unknown> {
return withRetry(
async () => {
const response = await snippetRunner.execute({
workflowName: config.workflowName,
stepId: step.id,
inputs: spec.inputs,
previousOutputs: context.previousOutputs,
...(step.timeoutSeconds !== undefined && { timeoutSeconds: step.timeoutSeconds }),
})
if (response.status === 'failed') {
throw new Error(response.error ?? 'snippet-step-failed')
}
return mergeSnippetArtifactsIntoOutput(response)
},
{
maxAttempts: step.maxRetries ?? step.retries ?? 1,
backoffSeconds: step.backoffSeconds ?? 30,
}
)
}
function recordStepMetrics(
step: RuntimeStepSpec,
status: 'succeeded' | 'failed',
durationMs: number
): void {
const executor = resolveExecutorKind(step)
const stepKind = isSnippetRun(step.run) ? 'snippet.typescript' : 'agentic'
const labels = {
executor,
stepKind,
status,
}
workflowStepTotal.inc(labels)
workflowStepDurationSeconds.observe(labels, Math.max(0, durationMs) / 1000)
}
function resolveExecutorKind(step: RuntimeStepSpec): 'agentic' | 'snippet' {
if (isSnippetRun(step.run)) return 'snippet'
return 'agentic'
}
function isSnippetRun(run: RuntimeStepSpec['run'] | undefined): run is SnippetRuntimeRunSpec {
return run?.type === 'snippet'
}
function isSnippetRuntimeStep(step: RuntimeStepSpec): step is SnippetRuntimeStepSpec {
return isSnippetRun(step.run)
}
function mergeSnippetArtifactsIntoOutput(response: SnippetExecuteResponse): unknown {
const artifacts = response.artifacts ?? []
if (artifacts.length === 0) return response.output
if (response.output && typeof response.output === 'object' && !Array.isArray(response.output)) {
const output = response.output as Record<string, unknown>
const existing = Array.isArray(output.artifacts) ? output.artifacts : []
return { ...output, artifacts: [...existing, ...artifacts] }
}
return { value: response.output, artifacts }
}
function resolveStepTimeoutSeconds(value: unknown): number {
if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_STEP_TIMEOUT_SECONDS
return Math.max(1, Math.floor(value))
}
function resolveStepAgent(
step: RuntimeStepSpec,
defaultAgent: RuntimeAgentSpec | undefined,
currentAgent: Pick<RuntimeAgentSpec, 'provider' | 'model'> | undefined
): RuntimeAgentSpec | undefined {
const provider = step.agent?.provider ?? defaultAgent?.provider ?? currentAgent?.provider
const model = step.agent?.model ?? defaultAgent?.model ?? currentAgent?.model
if (!provider || !model) return undefined
return { provider, model, ...(step.agent?.soul ? { soul: step.agent.soul } : {}) }
}
function resolveLastCompletedAgent(
orderedSteps: StepSpec[],
status: RuntimeStatusSnapshot,
defaultAgent: RuntimeAgentSpec | undefined
): Pick<RuntimeAgentSpec, 'provider' | 'model'> | undefined {
let current = defaultAgent
? { provider: defaultAgent.provider, model: defaultAgent.model }
: undefined
const statusByStep = new Map((status.steps ?? []).map(step => [step.id, step]))
for (const step of orderedSteps) {
const modelUsed = statusByStep.get(step.id)?.modelUsed
if (!modelUsed) continue
const [provider, model] = modelUsed.split('/')
if (isAgentProvider(provider) && model) current = { provider, model }
}
return current
}
function sleep(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms))
}
function isProviderOutputLengthExceeded(error: string | undefined): boolean {
return Boolean(error?.includes(PROVIDER_OUTPUT_LENGTH_EXCEEDED))
}
async function executeAgenticStepWithRetry(
mcpHost: McpHostClient,
step: RuntimeStepSpec,
instruction: string,
contextVars: Record<string, string>,
approvalBindingProof?: string
): Promise<AgentStepResult> {
const maxAttempts = step.maxRetries ?? step.retries ?? 2
const backoffSeconds = step.backoffSeconds ?? 30
if (maxAttempts < 1) {
throw new Error(`agentic step retry policy for "${step.id}" must allow at least 1 attempt`)
}
let lastError: Error | undefined
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
const result = await mcpHost.executeAgentStep({
stepId: step.id,
instruction,
mcpServers: step.mcpServers ?? [],
allowedTools: step.allowedTools ?? step.tools ?? {},
toolChoice: step.toolChoice,
maxIterations: step.maxIterations,
timeoutSeconds: step.timeoutSeconds,
contextVars,
...(approvalBindingProof ? { approvalBindingProof } : {}),
...(step.requiresApproval && { requiresApproval: step.requiresApproval }),
})
if (result.status === 'failed') {
throw new Error(result.error ?? 'agentic-step-failed')
}
return result
} catch (err) {
lastError = err instanceof Error ? err : new Error(String(err))
if (isProviderOutputLengthExceeded(lastError.message)) {
throw lastError
}
if (attempt < maxAttempts) {
const delayMs = computeBackoff(backoffSeconds, attempt) * 1000
if (delayMs > 0) await sleep(delayMs)
}
}
}
throw lastError ?? new Error('agentic-step-failed')
}
async function waitForMcpHostReady(
client: McpHostClient,
maxAttempts: number,
delayMs: number
): Promise<void> {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const health = await client.healthCheck()
if (health.status === 'healthy') return
if (attempt < maxAttempts) await new Promise(resolve => setTimeout(resolve, delayMs))
}
throw new McpHostReadinessTimeoutError()
}
async function readCurrentStatus(status: StatusReporter): Promise<RuntimeStatusSnapshot> {
try {
return await status.getWorkflowStatus()
} catch {
return { workflowPhase: 'pending', steps: [] }
}
}
async function reportRemainingAsSkipped(
orderedSteps: StepSpec[],
failedStepId: string,
status: StatusReporter
): Promise<void> {
const failedIndex = orderedSteps.findIndex(step => step.id === failedStepId)
if (failedIndex === -1) return
for (const step of orderedSteps.slice(failedIndex + 1)) {
await status.reportStepStatus(step.id, 'skipped')
}
}
function stringifyOutput(output: unknown): string {
return typeof output === 'string' ? output : JSON.stringify(output)
}
function isAgentProvider(value: string): value is AgentProvider {
return isLlmProviderId(value)
}
function parseRuntimeWorkflowSpec(spec: WorkflowRecipeSpec): RuntimeWorkflowSpec {
const rawSpec = asObject(spec, 'workflow spec')
const runtimeSpec: RuntimeWorkflowSpec = {
...spec,
steps: spec.steps.map((step, index) => parseRuntimeStepSpec(step, `steps[${index}]`)),
}
const agent = parseAgentSpec(rawSpec.agent, 'agent', false)
if (agent) runtimeSpec.agent = agent
return runtimeSpec
}
function parseRuntimeStepSpec(step: StepSpec, path: string): RuntimeStepSpec {
const rawStep = asObject(step, path)
const runtimeStep: RuntimeStepSpec = {
id: step.id,
...(step.instruction !== undefined && { instruction: step.instruction }),
...(step.dependsOn !== undefined && { dependsOn: step.dependsOn }),
...(step.timeoutSeconds !== undefined && {
timeoutSeconds: readPositiveIntegerField(step.timeoutSeconds, `${path}.timeoutSeconds`),
}),
...(step.retries !== undefined && {
retries: readPositiveIntegerField(step.retries, `${path}.retries`),
}),
...(step.backoffSeconds !== undefined && {
backoffSeconds: readNonNegativeIntegerField(step.backoffSeconds, `${path}.backoffSeconds`),
}),
...(step.tools !== undefined && { tools: step.tools }),
}
const maxRetries = rawStep.maxRetries
if (maxRetries !== undefined) {
runtimeStep.maxRetries = readPositiveIntegerField(maxRetries, `${path}.maxRetries`)
}
const maxIterations = rawStep.maxIterations
if (maxIterations !== undefined) {
runtimeStep.maxIterations = readPositiveIntegerField(maxIterations, `${path}.maxIterations`)
}
const allowedTools = parseAllowedTools(rawStep.allowedTools, `${path}.allowedTools`)
if (allowedTools) runtimeStep.allowedTools = allowedTools
const toolChoice = parseToolChoice(rawStep.toolChoice, `${path}.toolChoice`)
if (toolChoice) runtimeStep.toolChoice = toolChoice
const run = parseSnippetRun(rawStep.run, `${path}.run`)
if (run) runtimeStep.run = run
const mcpServers = parseMcpServers(rawStep.mcpServers, `${path}.mcpServers`)
if (mcpServers) runtimeStep.mcpServers = mcpServers
const agent = parseAgentSpec(rawStep.agent, `${path}.agent`, true)
if (agent) runtimeStep.agent = agent
const requiresApproval = parseApprovalSpec(rawStep.requiresApproval, `${path}.requiresApproval`)
if (requiresApproval) runtimeStep.requiresApproval = requiresApproval
return runtimeStep
}
function toCoordinatorWorkflowSpec(spec: RuntimeWorkflowSpec): WorkflowRecipeSpec {
return {
...spec,
...(spec.agent && {
agent: { provider: spec.agent.provider, model: spec.agent.model },
}),
steps: spec.steps.map(step => ({
id: step.id,
...(step.instruction !== undefined && { instruction: step.instruction }),
...(step.dependsOn !== undefined && { dependsOn: step.dependsOn }),
...(step.timeoutSeconds !== undefined && { timeoutSeconds: step.timeoutSeconds }),
...(step.retries !== undefined && { retries: step.retries }),
...(step.backoffSeconds !== undefined && { backoffSeconds: step.backoffSeconds }),
...(step.tools !== undefined && { tools: step.tools }),
...(step.toolChoice !== undefined && { toolChoice: step.toolChoice }),
...(step.run !== undefined && { run: step.run }),
})),
}
}
function parseToolChoice(value: unknown, path: string): 'auto' | 'none' | 'required' | undefined {
if (value === undefined) return undefined
if (value === 'auto' || value === 'none' || value === 'required') return value
throw new Error(`${path} must be one of: auto, none, required`)
}
function parseAllowedTools(value: unknown, path: string): { include?: string[] } | undefined {
if (value === undefined) return undefined
const raw = asObject(value, path)
const include = raw.include
if (include === undefined) return {}
if (!Array.isArray(include) || include.some(item => typeof item !== 'string')) {
throw new Error(`${path}.include must be an array of strings`)
}
return { include: [...include] }
}
function parseSnippetRun(value: unknown, path: string): SnippetRuntimeRunSpec | undefined {
if (value === undefined) return undefined
const raw = asObject(value, path)
assertAllowedKeys(raw, SNIPPET_RUN_KEYS, path)
if (raw.type !== 'snippet') {
throw new Error(`${path}.type must be snippet`)
}
if (raw.language !== 'typescript') {
throw new Error(`${path}.language must be typescript`)
}
if (typeof raw.code !== 'string' || raw.code.trim() === '') {
throw new Error(`${path}.code must be a non-empty string`)
}
if (raw.capabilities !== undefined) {
asObject(raw.capabilities, `${path}.capabilities`)
}
return {
type: 'snippet',
language: 'typescript',
code: raw.code,
...(raw.capabilities !== undefined && {
capabilities: raw.capabilities as SnippetRuntimeRunSpec['capabilities'],
}),
}
}
function parseMcpServers(value: unknown, path: string): StepMcpServerRef[] | undefined {
if (value === undefined) return undefined
if (!Array.isArray(value)) throw new Error(`${path} must be an array`)
return value.map((item, index) => parseMcpServerRef(item, `${path}[${index}]`))
}
function parseMcpServerRef(value: unknown, path: string): StepMcpServerRef {
const raw = asObject(value, path)
if (typeof raw.name !== 'string' || raw.name.trim() === '') {
throw new Error(`${path}.name must be a non-empty string`)
}
if (typeof raw.url !== 'string' || raw.url.trim() === '') {
throw new Error(`${path}.url must be a non-empty string`)
}
return { name: raw.name, url: raw.url }
}
function parseAgentSpec(
value: unknown,
path: string,
allowPartial: true
): Partial<RuntimeAgentSpec> | undefined
function parseAgentSpec(
value: unknown,
path: string,
allowPartial: false
): RuntimeAgentSpec | undefined
function parseAgentSpec(
value: unknown,
path: string,
allowPartial: boolean
): Partial<RuntimeAgentSpec> | RuntimeAgentSpec | undefined {
if (value === undefined) return undefined
const raw = asObject(value, path)
const provider = raw.provider
const model = raw.model
const soul = raw.soul
if (provider !== undefined && (typeof provider !== 'string' || !isAgentProvider(provider))) {
throw new Error(`${path}.provider must be a supported provider`)
}
if (model !== undefined && (typeof model !== 'string' || model.trim() === '')) {
throw new Error(`${path}.model must be a non-empty string`)
}
if (soul !== undefined && (typeof soul !== 'string' || soul.trim() === '')) {
throw new Error(`${path}.soul must be a non-empty string`)
}
if (!allowPartial && (!provider || !model)) {
throw new Error(`${path} must include provider and model`)
}
return {
...(provider !== undefined && { provider: provider as AgentProvider }),
...(model !== undefined && { model }),
...(soul !== undefined && { soul }),
}
}
function parseApprovalSpec(value: unknown, path: string): ApprovalSpec | undefined {
if (value === undefined) return undefined
const raw = asObject(value, path)
const target = asObject(raw.target, `${path}.target`)
if (target.userId !== undefined && typeof target.userId !== 'string') {
throw new Error(`${path}.target.userId must be a string`)
}
if (target.teamId !== undefined && typeof target.teamId !== 'string') {
throw new Error(`${path}.target.teamId must be a string`)
}
if (typeof raw.message !== 'string' || raw.message.trim() === '') {
throw new Error(`${path}.message must be a non-empty string`)
}
const timeoutSeconds =
raw.timeoutSeconds === undefined
? undefined
: readPositiveIntegerField(raw.timeoutSeconds, `${path}.timeoutSeconds`)
return {
target: {
...(target.userId !== undefined && { userId: target.userId }),
...(target.teamId !== undefined && { teamId: target.teamId }),
},
message: raw.message,
...(timeoutSeconds !== undefined && { timeoutSeconds }),
}
}
function asObject(value: unknown, path: string): UnknownObject {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw new Error(`${path} must be an object`)
}
return value as UnknownObject
}
function assertAllowedKeys(value: UnknownObject, allowedKeys: Set<string>, path: string): void {
for (const key of Object.keys(value)) {
if (!allowedKeys.has(key)) {
throw new Error(`${path} contains unsupported field "${key}"`)
}
}
}
function readPositiveIntegerField(value: unknown, path: string): number {
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
throw new Error(`${path} must be a positive integer`)
}
return value
}
function readNonNegativeIntegerField(value: unknown, path: string): number {
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
throw new Error(`${path} must be a non-negative integer`)
}
return value
}