@ariaflowagents/config 0.5.3 → 0.8.0

package/dist/llm-flow-generator.js

@@ -0,0 +1,244 @@
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+import { generateFlowTemplate } from './flow-generator.js';
+const fullPromptBlocksSchema = z.object({
+    globalPrompt: z
+        .string()
+        .min(1)
+        .describe('Global role prompt with sections for overall goal, language/style rules, tool+transition rules, and reliability rules.'),
+    mainAgendaPrompt: z
+        .string()
+        .min(1)
+        .describe('Main agenda prompt with concrete stage tasks, required data, relevant questions, and strict transition success criteria.'),
+});
+const taskBlockSchema = z.object({
+    title: z.string().min(1).max(120),
+    details: z.array(z.string().min(1).max(280)).min(1).max(6),
+    questions: z.array(z.string().min(1).max(280)).min(1).max(6),
+    finalActions: z.array(z.string().min(1).max(280)).min(1).max(6),
+});
+const hybridDraftSchema = z.object({
+    goalDescription: z.string().min(1).max(420),
+    useCases: z.array(z.string().min(1).max(280)).min(1).max(8),
+    fallbackOptions: z.array(z.string().min(1).max(280)).min(1).max(6),
+    taskBlocks: z.array(taskBlockSchema).min(1).max(6),
+    summaryMoveCriteria: z.array(z.string().min(1).max(280)).min(1).max(8),
+});
+function buildFullLlmPrompt(options) {
+    const contextSection = options.contextText && options.contextText.trim().length > 0
+        ? `\n## Additional Context\n${options.contextText.trim()}\n`
+        : '';
+    return `Generate production-grade flow prompts for a voice-first guided agent.
+
+## Use Case
+- agent name: ${options.agentName}
+- direction: ${options.direction}
+- use case: ${options.useCase}
+${contextSection}
+## Output Requirements
+- Return ONLY structured fields via the schema.
+- globalPrompt must include:
+  - OVERALL GOAL section
+  - response language/style rules
+  - tool/function transition discipline
+  - reliability / non-hallucination rules
+- mainAgendaPrompt must include:
+  - "MAIN ACTION POINT AT THIS STEP"
+  - 3-5 task blocks
+  - each task block has details/data + relevant questions + final actions
+  - explicit success criteria for moving to summary stage
+- Make questions concrete and domain-specific, not generic filler.
+- Enforce deterministic behavior: one question at a time, no mixing text+tool transition output.
+- Keep wording clear for spoken conversations.
+- Do not include markdown code fences.`;
+}
+function buildHybridLlmPrompt(options) {
+    const contextSection = options.contextText && options.contextText.trim().length > 0
+        ? `\n## Additional Context\n${options.contextText.trim()}\n`
+        : '';
+    return `Create domain-specific variable blocks for a voice flow.
+Do NOT output full prompts. Return only fields in schema.
+
+## Use Case
+- agent name: ${options.agentName}
+- direction: ${options.direction}
+- use case: ${options.useCase}
+${contextSection}
+## Constraints
+- Keep content specific and realistic for the use case.
+- Avoid generic filler.
+- Questions should be voice-friendly and one-at-a-time.
+- Include only facts/steps that can be asked or verified in conversation.
+- No markdown code fences.`;
+}
+function composeHybridGlobalPrompt(options, draft) {
+    const useCases = draft.useCases.map(item => item.trim()).filter(Boolean);
+    const fallbacks = draft.fallbackOptions.map(item => item.trim()).filter(Boolean);
+    const effectiveUseCases = useCases.length > 0 ? useCases : ['addressing user requests and collecting required details'];
+    const effectiveFallbacks = fallbacks.length > 0 ? fallbacks : ['providing a concise summary and a follow-up option'];
+    const goal = draft.goalDescription.trim().length > 0
+        ? draft.goalDescription.trim()
+        : 'handling user requests accurately and moving toward clear resolution';
+    const useCaseLines = effectiveUseCases.map(item => `- ${item}`).join('\n');
+    const fallbackLines = effectiveFallbacks.map(item => `- ${item}`).join('\n');
+    return `# OVERALL GOAL
+
+You are ${options.agentName}. You are handling ${options.direction} calls for this use case.
+Primary goal: ${goal}
+
+Support these common scenarios:
+${useCaseLines}
+
+If the caller is hesitant, confused, or does not wish to continue, offer alternatives such as:
+${fallbackLines}
+
+## Response Language
+YOU MUST only REPLY IN the language of the latest user input. Use simple words, keep tone informal but professional, and keep answers concise for voice.
+
+## Critical Rules
+- If the last message is not a user message, do not make a function/tool call.
+- Never mix text and tool calls in the same output.
+- Ask one focused question at a time and wait for the user response.
+- If a transition is required, end the turn with the correct tool call or a question, never both.
+
+## Reliability Rules
+- Do not invent facts. If uncertain, ask a clarifying question or use a verification tool.
+- Keep collected details consistent across turns and avoid contradictions.
+- Prefer deterministic next actions over vague responses.`;
+}
+function composeHybridMainAgendaPrompt(draft) {
+    const blocks = draft.taskBlocks
+        .map((block, index) => {
+        const detailsList = block.details.map(item => item.trim()).filter(Boolean);
+        const questionList = block.questions.map(item => item.trim()).filter(Boolean);
+        const actionList = block.finalActions.map(item => item.trim()).filter(Boolean);
+        const details = (detailsList.length > 0 ? detailsList : ['Collect the required data for this step.'])
+            .map(item => `  - ${item}`).join('\n');
+        const questions = (questionList.length > 0 ? questionList : ['What is the key detail needed to proceed?'])
+            .map(item => `  - ${item}`).join('\n');
+        const actions = (actionList.length > 0 ? actionList : ['Summarize captured inputs and proceed deterministically.'])
+            .map(item => `  - ${item}`).join('\n');
+        const title = block.title.trim().length > 0 ? block.title.trim() : `Step ${index + 1}`;
+        return `### Task ${index + 1}: ${title}
+Details and Data:
+${details}
+Relevant Questions:
+${questions}
+Final Step and Related Actions:
+${actions}`;
+    })
+        .join('\n\n');
+    const successCriteriaList = draft.summaryMoveCriteria
+        .map(item => item.trim())
+        .filter(Boolean);
+    const successCriteria = (successCriteriaList.length > 0
+        ? successCriteriaList
+        : ['Required details are collected and validated', 'A clear next action is identified'])
+        .map(item => `- ${item}`)
+        .join('\n');
+    return `# MAIN ACTION POINT AT THIS STEP
+## Usable details and Main Agenda
+
+## USABLE DETAILS and GOALS AT THIS STAGE:
+${blocks}
+
+## Flow of call
+Here’s how the flow should work:
+- Ask one question at a time.
+- Handle objections briefly, then continue the agenda.
+- Do not loop or repeat already-confirmed questions.
+- Use transition tools/events to move stages.
+
+# Success criteria WHEN you can move to next step
+${successCriteria}
+- Transition to Summary using the designated transition tool/event only.`;
+}
+function runWithTimeout(promise, timeoutMs, timeoutMessage) {
+    let timeoutHandle;
+    const timeout = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    });
+}
+async function generateObjectStrict({ model, schema, system, prompt, }) {
+    const result = await generateObject({
+        model,
+        schema,
+        system,
+        prompt,
+    });
+    return result.object;
+}
+function resolveModelSpec(modelInput) {
+    const requested = modelInput?.trim() || 'gpt-5-mini';
+    const modelId = requested.startsWith('openai:') ? requested.slice('openai:'.length).trim() : requested;
+    if (!modelId) {
+        throw new Error('Model id cannot be empty');
+    }
+    if (!process.env.OPENAI_API_KEY || process.env.OPENAI_API_KEY.trim().length === 0) {
+        throw new Error('OPENAI_API_KEY is required for LLM flow generation');
+    }
+    return {
+        modelId,
+        label: `openai:${modelId}`,
+        model: openai(modelId),
+    };
+}
+export async function generateFlowTemplateWithLLM(options) {
+    const useCase = options.useCase.trim();
+    const direction = options.direction ?? 'inbound';
+    const agentName = options.agentName?.trim() || 'Sam';
+    const modelSpec = resolveModelSpec(options.model);
+    const timeoutMs = options.timeoutMs ?? 45000;
+    const llmMode = options.llmMode ?? 'hybrid';
+    if (llmMode === 'full') {
+        const generate = generateObjectStrict({
+            model: modelSpec.model,
+            schema: fullPromptBlocksSchema,
+            system: 'You are an expert prompt engineer for deterministic conversational flow agents. Produce concise, robust prompts only.',
+            prompt: buildFullLlmPrompt({
+                useCase,
+                direction,
+                agentName,
+                contextText: options.contextText,
+            }),
+        });
+        const object = await runWithTimeout(generate, timeoutMs, `LLM flow generation timed out after ${timeoutMs}ms (${modelSpec.label})`);
+        return generateFlowTemplate({
+            ...options,
+            promptBlocks: {
+                ...options.promptBlocks,
+                globalPrompt: object.globalPrompt.trim(),
+                mainAgendaPrompt: object.mainAgendaPrompt.trim(),
+            },
+        });
+    }
+    let draft;
+    draft = await runWithTimeout(generateObjectStrict({
+        model: modelSpec.model,
+        schema: hybridDraftSchema,
+        system: 'You generate domain-specific variable blocks for conversational flow prompts. Keep content concrete and deterministic.',
+        prompt: buildHybridLlmPrompt({
+            useCase,
+            direction,
+            agentName,
+            contextText: options.contextText,
+        }),
+    }), timeoutMs, `LLM flow generation timed out after ${timeoutMs}ms (${modelSpec.label})`);
+    const globalPrompt = composeHybridGlobalPrompt({ direction, agentName }, draft);
+    const mainAgendaPrompt = composeHybridMainAgendaPrompt(draft);
+    return generateFlowTemplate({
+        ...options,
+        promptBlocks: {
+            ...options.promptBlocks,
+            globalPrompt,
+            mainAgendaPrompt,
+        },
+    });
+}
+//# sourceMappingURL=llm-flow-generator.js.map

package/dist/llm-flow-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-flow-generator.js","sourceRoot":"","sources":["../src/llm-flow-generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAA8B,MAAM,qBAAqB,CAAC;AAUvF,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,wHAAwH,CACzH;IACH,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,0HAA0H,CAC3H;CACJ,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAChE,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACvE,CAAC,CAAC;AAIH,SAAS,kBAAkB,CAAC,OAE3B;IACC,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACjF,CAAC,CAAC,4BAA4B,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI;QAC5D,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;;;gBAGO,OAAO,CAAC,SAAS;eAClB,OAAO,CAAC,SAAS;cAClB,OAAO,CAAC,OAAO;EAC3B,cAAc;;;;;;;;;;;;;;;;uCAgBuB,CAAC;AACxC,CAAC;AAED,SAAS,oBAAoB,CAAC,OAE7B;IACC,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACjF,CAAC,CAAC,4BAA4B,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI;QAC5D,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;;;;gBAIO,OAAO,CAAC,SAAS;eAClB,OAAO,CAAC,SAAS;cAClB,OAAO,CAAC,OAAO;EAC3B,cAAc;;;;;;2BAMW,CAAC;AAC5B,CAAC;AAED,SAAS,yBAAyB,CAChC,OAAyE,EACzE,KAAkB;IAElB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjF,MAAM,iBAAiB,GACrB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,0DAA0D,CAAC,CAAC;IAChG,MAAM,kBAAkB,GACtB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,oDAAoD,CAAC,CAAC;IAC5F,MAAM,IAAI,GACR,KAAK,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACrC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,EAAE;QAC9B,CAAC,CAAC,sEAAsE,CAAC;IAE7E,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,MAAM,aAAa,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE7E,OAAO;;UAEC,OAAO,CAAC,SAAS,sBAAsB,OAAO,CAAC,SAAS;gBAClD,IAAI;;;EAGlB,YAAY;;;EAGZ,aAAa;;;;;;;;;;;;;;0DAc2C,CAAC;AAC3D,CAAC;AAED,SAAS,6BAA6B,CAAC,KAAkB;IACvD,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU;SAC5B,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3E,MAAM,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9E,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/E,MAAM,OAAO,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC;aAClG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,2CAA2C,CAAC,CAAC;aACvG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,0DAA0D,CAAC,CAAC;aAChH,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,EAAE,CAAC;QACvF,OAAO,YAAY,KAAK,GAAG,CAAC,KAAK,KAAK;;EAE1C,OAAO;;EAEP,SAAS;;EAET,OAAO,EAAE,CAAC;IACR,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,MAAM,mBAAmB,GAAG,KAAK,CAAC,mBAAmB;SAClD,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SACxB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,MAAM,eAAe,GAAG,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC;QACrD,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,CAAC,8CAA8C,EAAE,mCAAmC,CAAC,CAAC;SACvF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;SACxB,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;;;;EAIP,MAAM;;;;;;;;;;EAUN,eAAe;yEACwD,CAAC;AAC1E,CAAC;AAED,SAAS,cAAc,CAAI,OAAmB,EAAE,SAAiB,EAAE,cAAsB;IACvF,IAAI,aAAwD,CAAC;IAC7D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC/C,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACjF,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;QACnD,IAAI,aAAa,EAAE,CAAC;YAClB,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAI,EACrC,KAAK,EACL,MAAM,EACN,MAAM,EACN,MAAM,GAMP;IACC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;QAClC,KAAK;QACL,MAAM;QACN,MAAM;QACN,MAAM;KACP,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,SAAS,gBAAgB,CAAC,UAA8B;IAKtD,MAAM,SAAS,GAAG,UAAU,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC;IACrD,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEvG,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,OAAO;QACL,OAAO;QACP,KAAK,EAAE,UAAU,OAAO,EAAE;QAC1B,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC;KACvB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAiC;IAEjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,SAAS,CAAC;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC;IACrD,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;IAE5C,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,oBAAoB,CAAC;YACpC,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,MAAM,EAAE,sBAAsB;YAC9B,MAAM,EACJ,uHAAuH;YACzH,MAAM,EAAE,kBAAkB,CAAC;gBACzB,OAAO;gBACP,SAAS;gBACT,SAAS;gBACT,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC;SACH,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,QAAQ,EACR,SAAS,EACT,uCAAuC,SAAS,OAAO,SAAS,CAAC,KAAK,GAAG,CAC1E,CAAC;QAEF,OAAO,oBAAoB,CAAC;YAC1B,GAAG,OAAO;YACV,YAAY,EAAE;gBACZ,GAAG,OAAO,CAAC,YAAY;gBACvB,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE;gBACxC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE;aACjD;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAkB,CAAC;IACvB,KAAK,GAAG,MAAM,cAAc,CAC1B,oBAAoB,CAAC;QACnB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,MAAM,EAAE,iBAAiB;QACzB,MAAM,EACJ,wHAAwH;QAC1H,MAAM,EAAE,oBAAoB,CAAC;YAC3B,OAAO;YACP,SAAS;YACT,SAAS;YACT,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC;KACH,CAAC,EACF,SAAS,EACT,uCAAuC,SAAS,OAAO,SAAS,CAAC,KAAK,GAAG,CAC1E,CAAC;IAEF,MAAM,YAAY,GAAG,yBAAyB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,KAAK,CAAC,CAAC;IAChF,MAAM,gBAAgB,GAAG,6BAA6B,CAAC,KAAK,CAAC,CAAC;IAE9D,OAAO,oBAAoB,CAAC;QAC1B,GAAG,OAAO;QACV,YAAY,EAAE;YACZ,GAAG,OAAO,CAAC,YAAY;YACvB,YAAY;YACZ,gBAAgB;SACjB;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/loader.d.ts

@@ -1,6 +1,6 @@
 import { type HarnessConfig, type Runtime } from '@ariaflowagents/core';
 import type { LoadedConfig, LoadOptions } from './types.js';
-type WarningType = 'invalid_frontmatter' | 'missing_prompt' | 'missing_template' | 'name_mismatch' | 'missing_ref' | 'invalid_tool_entry' | 'duplicate_agent' | 'duplicate_flow' | 'unresolved_flow_ref' | 'tool_not_found';
+type WarningType = 'invalid_frontmatter' | 'invalid_flow' | 'missing_prompt' | 'missing_template' | 'name_mismatch' | 'missing_ref' | 'invalid_tool_entry' | 'duplicate_agent' | 'duplicate_flow' | 'unresolved_flow_ref' | 'tool_not_found';
 interface ConfigWarning {
     type: WarningType;
     file: string;

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAUL,KAAK,aAAa,EAElB,KAAK,OAAO,EAGb,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAKV,YAAY,EACZ,WAAW,EAMZ,MAAM,YAAY,CAAC;AAqDpB,KAAK,WAAW,GACZ,qBAAqB,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,UAAU,aAAa;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAmgCD,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+QzF;AAED,wBAAsB,4BAA4B,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;IACrF,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC,CAoSD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAanH;AA6FD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,gBAAgB,GAAG,cAAc,CAAC,CAAM,GACzF,OAAO,CAYT"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAWA,OAAO,EAUL,KAAK,aAAa,EAElB,KAAK,OAAO,EAGb,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAKV,YAAY,EACZ,WAAW,EAMZ,MAAM,YAAY,CAAC;AAqDpB,KAAK,WAAW,GACZ,qBAAqB,GACrB,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,UAAU,aAAa;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AA8rCD,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuQzF;AAED,wBAAsB,4BAA4B,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;IACrF,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC,CA4RD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAanH;AA+FD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,gBAAgB,GAAG,cAAc,CAAC,CAAM,GACzF,OAAO,CAYT"}

package/dist/loader.js

@@ -108,6 +108,160 @@ function deepMerge(base, override) {
     }
     return result;
 }
+const VALID_FLOW_NODE_TYPES = new Set(['start', 'agent', 'end', 'global']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeAndValidateFlowInput(flowId, flowInput, sourcePath) {
+    const errors = [];
+    if (!Array.isArray(flowInput.nodes) || flowInput.nodes.length === 0) {
+        errors.push('must define at least one node');
+    }
+    const normalizedNodes = [];
+    const nodeIds = new Set();
+    let startNodeCount = 0;
+    let globalNodeCount = 0;
+    let detectedStartNodeId;
+    for (let i = 0; i < (Array.isArray(flowInput.nodes) ? flowInput.nodes.length : 0); i++) {
+        const rawNode = flowInput.nodes[i];
+        if (!isRecord(rawNode)) {
+            errors.push(`node[${i}] must be an object`);
+            continue;
+        }
+        const node = rawNode;
+        const nodeId = typeof node.id === 'string' ? node.id.trim() : '';
+        if (!nodeId) {
+            errors.push(`node[${i}] is missing a valid "id"`);
+            continue;
+        }
+        if (nodeIds.has(nodeId)) {
+            errors.push(`duplicate node id "${nodeId}"`);
+            continue;
+        }
+        nodeIds.add(nodeId);
+        if (typeof node.prompt !== 'string' || node.prompt.trim().length === 0) {
+            errors.push(`node "${nodeId}" is missing a non-empty "prompt"`);
+        }
+        const nodeType = typeof node.nodeType === 'string' ? node.nodeType : undefined;
+        if (nodeType && !VALID_FLOW_NODE_TYPES.has(nodeType)) {
+            errors.push(`node "${nodeId}" has invalid nodeType "${nodeType}" (allowed: start, agent, end, global)`);
+        }
+        if (nodeType === 'start') {
+            startNodeCount += 1;
+            detectedStartNodeId = detectedStartNodeId ?? nodeId;
+        }
+        if (nodeType === 'global') {
+            globalNodeCount += 1;
+        }
+        normalizedNodes.push({
+            ...node,
+            id: nodeId,
+            addGlobalPrompt: node.addGlobalPrompt !== false,
+            ...(nodeType
+                ? { nodeType: nodeType }
+                : {}),
+        });
+    }
+    if (startNodeCount > 1) {
+        errors.push('must have at most one node with nodeType="start"');
+    }
+    if (globalNodeCount > 1) {
+        errors.push('must have at most one node with nodeType="global"');
+    }
+    const normalizedTransitions = [];
+    if (flowInput.transitions !== undefined && !Array.isArray(flowInput.transitions)) {
+        errors.push('"transitions" must be an array when provided');
+    }
+    if (Array.isArray(flowInput.transitions)) {
+        for (let i = 0; i < flowInput.transitions.length; i++) {
+            const rawTransition = flowInput.transitions[i];
+            if (!isRecord(rawTransition)) {
+                errors.push(`transition[${i}] must be an object`);
+                continue;
+            }
+            const transition = rawTransition;
+            const from = typeof transition.from === 'string' ? transition.from.trim() : '';
+            const to = typeof transition.to === 'string' ? transition.to.trim() : '';
+            if (!from || !to) {
+                errors.push(`transition[${i}] must include non-empty "from" and "to"`);
+                continue;
+            }
+            if (!nodeIds.has(from)) {
+                errors.push(`transition[${i}] references unknown "from" node "${from}"`);
+            }
+            if (!nodeIds.has(to)) {
+                errors.push(`transition[${i}] references unknown "to" node "${to}"`);
+            }
+            const on = typeof transition.on === 'string' ? transition.on.trim() : transition.on;
+            if (transition.on !== undefined && (!on || typeof on !== 'string')) {
+                errors.push(`transition[${i}] has invalid "on" value`);
+            }
+            const hasConditionFn = typeof transition.condition === 'function';
+            if (transition.condition !== undefined && !hasConditionFn) {
+                errors.push(`transition[${i}] has non-function "condition"`);
+            }
+            if (!on && !hasConditionFn) {
+                errors.push(`transition[${i}] must define either "on" or "condition"`);
+            }
+            let contract;
+            if (transition.contract !== undefined) {
+                if (!isRecord(transition.contract)) {
+                    errors.push(`transition[${i}] has invalid "contract" (must be an object)`);
+                }
+                else {
+                    const rawContract = transition.contract;
+                    contract = {
+                        label: typeof rawContract.label === 'string' ? rawContract.label : undefined,
+                        conditionText: typeof rawContract.conditionText === 'string'
+                            ? rawContract.conditionText
+                            : undefined,
+                        toolOnly: typeof rawContract.toolOnly === 'boolean' ? rawContract.toolOnly : undefined,
+                        requiresUserTurn: typeof rawContract.requiresUserTurn === 'boolean'
+                            ? rawContract.requiresUserTurn
+                            : undefined,
+                    };
+                }
+            }
+            normalizedTransitions.push({
+                ...transition,
+                from,
+                to,
+                ...(typeof on === 'string' ? { on } : {}),
+                ...(contract ? { contract } : {}),
+            });
+        }
+    }
+    const explicitInitialNode = typeof flowInput.initialNode === 'string' && flowInput.initialNode.trim().length > 0
+        ? flowInput.initialNode.trim()
+        : typeof flowInput.entry === 'string' && flowInput.entry.trim().length > 0
+            ? flowInput.entry.trim()
+            : undefined;
+    const initialNode = explicitInitialNode ?? detectedStartNodeId ?? normalizedNodes[0]?.id;
+    if (!initialNode) {
+        errors.push('could not resolve initial node');
+    }
+    else if (!nodeIds.has(initialNode)) {
+        errors.push(`initial node "${initialNode}" is not present in nodes`);
+    }
+    if (errors.length > 0) {
+        const formatted = errors.map(err => `- ${err}`).join('\n');
+        warn('invalid_flow', sourcePath, `Flow "${flowId}" is invalid:\n${formatted}`, 'error');
+        throw new Error(`Flow "${flowId}" is invalid in ${sourcePath}:\n${formatted}`);
+    }
+    const flow = {
+        nodes: normalizedNodes,
+        transitions: normalizedTransitions.length > 0 ? normalizedTransitions : undefined,
+        defaultRolePrompt: flowInput.defaultRolePrompt,
+        contextStrategy: flowInput.contextStrategy,
+        summaryPrompt: flowInput.summaryPrompt,
+        summaryMaxTokens: flowInput.summaryMaxTokens,
+        maxSteps: flowInput.maxSteps,
+        ...(typeof flowInput.summaryTimeoutMs === 'number'
+            ? { summaryTimeoutMs: flowInput.summaryTimeoutMs }
+            : {}),
+    };
+    return { flow, initialNode: initialNode };
+}
 function resolveConfigFile(target, baseDir) {
     const resolved = path.isAbsolute(target) ? target : path.resolve(baseDir, target);
     if (existsSync(resolved) && !resolved.endsWith('.json') && !resolved.endsWith('.jsonc')) {
@@ -444,17 +598,11 @@ async function loadFlowFiles(root, sources) {
         const content = await readFile(file, 'utf8');
         const data = parseJsoncContent(content, file);
         const id = data.id ?? path.basename(file, path.extname(file));
-        const { id: _id, entry, initialNode, ...rest } = data;
-        const flowConfig = {
-            nodes: rest.nodes,
-            transitions: rest.transitions,
-            defaultRolePrompt: rest.defaultRolePrompt,
-            contextStrategy: rest.contextStrategy,
-        };
-        flows[id] = flowConfig;
+        const normalized = normalizeAndValidateFlowInput(id, data, file);
+        flows[id] = normalized.flow;
         meta[id] = {
             id,
-            initialNode: initialNode ?? entry,
+            initialNode: normalized.initialNode,
             path: file,
         };
         sources.flowFiles.push(file);
@@ -965,13 +1113,9 @@ export async function loadAriaflowConfig(options = {}) {
             continue;
         }
         for (const [id, flowInput] of Object.entries(layer.config.flows)) {
-            flows[id] = {
-                nodes: flowInput.nodes,
-                transitions: flowInput.transitions,
-                defaultRolePrompt: flowInput.defaultRolePrompt,
-                contextStrategy: flowInput.contextStrategy,
-            };
-            flowMeta[id] = { id, initialNode: flowInput.initialNode ?? flowInput.entry, path: layer.path };
+            const normalized = normalizeAndValidateFlowInput(id, flowInput, layer.path);
+            flows[id] = normalized.flow;
+            flowMeta[id] = { id, initialNode: normalized.initialNode, path: layer.path };
         }
     }
     for (const root of roots) {
@@ -981,13 +1125,9 @@ export async function loadAriaflowConfig(options = {}) {
     }
     if (inlineLayer?.config.flows) {
         for (const [id, flowInput] of Object.entries(inlineLayer.config.flows)) {
-            flows[id] = {
-                nodes: flowInput.nodes,
-                transitions: flowInput.transitions,
-                defaultRolePrompt: flowInput.defaultRolePrompt,
-                contextStrategy: flowInput.contextStrategy,
-            };
-            flowMeta[id] = { id, initialNode: flowInput.initialNode ?? flowInput.entry, path: inlineLayer.path };
+            const normalized = normalizeAndValidateFlowInput(id, flowInput, inlineLayer.path);
+            flows[id] = normalized.flow;
+            flowMeta[id] = { id, initialNode: normalized.initialNode, path: inlineLayer.path };
         }
     }
     const agentDefs = {};
@@ -1176,13 +1316,9 @@ export async function loadAriaflowConfigWithResult(options = {}) {
         if (!layer.config.flows)
             continue;
         for (const [id, flowInput] of Object.entries(layer.config.flows)) {
-            flows[id] = {
-                nodes: flowInput.nodes,
-                transitions: flowInput.transitions,
-                defaultRolePrompt: flowInput.defaultRolePrompt,
-                contextStrategy: flowInput.contextStrategy,
-            };
-            flowMeta[id] = { id, initialNode: flowInput.initialNode ?? flowInput.entry, path: layer.path };
+            const normalized = normalizeAndValidateFlowInput(id, flowInput, layer.path);
+            flows[id] = normalized.flow;
+            flowMeta[id] = { id, initialNode: normalized.initialNode, path: layer.path };
         }
     }
     for (const root of roots) {
@@ -1192,13 +1328,9 @@ export async function loadAriaflowConfigWithResult(options = {}) {
     }
     if (inlineLayer?.config.flows) {
         for (const [id, flowInput] of Object.entries(inlineLayer.config.flows)) {
-            flows[id] = {
-                nodes: flowInput.nodes,
-                transitions: flowInput.transitions,
-                defaultRolePrompt: flowInput.defaultRolePrompt,
-                contextStrategy: flowInput.contextStrategy,
-            };
-            flowMeta[id] = { id, initialNode: flowInput.initialNode ?? flowInput.entry, path: inlineLayer.path };
+            const normalized = normalizeAndValidateFlowInput(id, flowInput, inlineLayer.path);
+            flows[id] = normalized.flow;
+            flowMeta[id] = { id, initialNode: normalized.initialNode, path: inlineLayer.path };
         }
     }
     const agentDefs = {};
@@ -1396,13 +1528,11 @@ async function normalizeAgentInput(id, input, baseDir, flows, flowMeta, toolRegi
             ? flowInput.mode
             : undefined;
         const flowId = flowInput.flowRef ?? flowInput.flow?.id;
-        const flowConfig = flowInput.flow
-            ? {
-                nodes: flowInput.flow.nodes,
-                transitions: flowInput.flow.transitions,
-                defaultRolePrompt: flowInput.flow.defaultRolePrompt,
-                contextStrategy: flowInput.flow.contextStrategy,
-            }
+        const inlineFlowNormalized = flowInput.flow
+            ? normalizeAndValidateFlowInput(flowId ?? `${id}-inline-flow`, flowInput.flow, `${baseDir}#agent:${id}`)
+            : null;
+        const flowConfig = inlineFlowNormalized
+            ? inlineFlowNormalized.flow
             : flowId
                 ? flows[flowId]
                 : undefined;
@@ -1410,7 +1540,7 @@ async function normalizeAgentInput(id, input, baseDir, flows, flowMeta, toolRegi
             throw new Error(`Flow agent "${id}" references missing flow`);
         }
         const initialNode = flowInput.initialNode ??
-            flowInput.flow?.entry ??
+            inlineFlowNormalized?.initialNode ??
             flowMeta[flowId ?? '']?.initialNode ??
             flowConfig.nodes?.[0]?.id;
         if (!initialNode) {