@synergenius/flow-weaver 0.2.0

package/dist/cli/templates/workflows/ai-agent-durable.js

@@ -0,0 +1,338 @@
+import { getProviderCode } from '../providers/index.js';
+import { aiConfigSchema } from './ai-agent.js';
+import { LLM_CORE_TYPES, LLM_MOCK_PROVIDER_WITH_TOOLS } from '../shared/llm-types.js';
+export const aiAgentDurableTemplate = {
+    id: 'ai-agent-durable',
+    name: 'Durable AI Agent',
+    description: 'Linear agent pipeline with durability — classify, tools, approval, respond',
+    category: 'ai',
+    configSchema: aiConfigSchema,
+    generate: ({ workflowName, config }) => {
+        const provider = config?.provider || 'mock';
+        const model = config?.model || '';
+        const providerCode = provider === 'mock'
+            ? `
+/* ============================================================
+ * MOCK PROVIDER (REPLACE IN REAL USE)
+ * ============================================================ */
+
+${LLM_MOCK_PROVIDER_WITH_TOOLS}
+`
+            : getProviderCode(provider, model);
+        return `
+// ============================================================
+// Durable AI Agent
+// ============================================================
+//
+// Each node becomes a checkpointed step when compiled to Inngest.
+// If a step fails, it retries from that step — not from scratch.
+//
+// Compile:  flow-weaver compile <file>
+// Export:   fw export --target inngest
+//
+// Flow: classify → executeTool → requestApproval → respond
+
+/* ============================================================
+ * CORE TYPES
+ * ============================================================ */
+
+${LLM_CORE_TYPES}
+
+/* ============================================================
+ * TOOL DEFINITIONS
+ * ============================================================ */
+
+type ToolResult =
+  | { ok: true; value: string }
+  | { ok: false; error: string };
+
+type ToolFn = (args: Record<string, unknown>) => Promise<ToolResult>;
+
+const AVAILABLE_TOOLS: LLMTool[] = [
+  {
+    name: 'search',
+    description: 'Search for information',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
+  async search(args) {
+    if (typeof args.query !== 'string') {
+      return { ok: false, error: 'Invalid query' };
+    }
+    return { ok: true, value: '[Search results for: ' + args.query + ']' };
+  },
+};
+
+/* ============================================================
+ * APPROVAL BACKEND (mock — replace with real backend)
+ * ============================================================
+ *
+ * On Inngest targets, this node compiles to step.waitForEvent().
+ * The function pauses (zero compute cost) until an approval event arrives.
+ */
+
+interface ApprovalResult {
+  approved: boolean;
+  response: string;
+  reviewer: string;
+}
+
+async function requestApproval(prompt: string, context?: Record<string, unknown>): Promise<ApprovalResult> {
+  console.log('[Mock Approval] Auto-approving:', prompt);
+  return { approved: true, response: 'Auto-approved (mock)', reviewer: 'system' };
+}
+
+${providerCode}
+
+const SYSTEM_PROMPT = \`You are a helpful AI assistant with access to tools.
+Use tools when necessary. Respond directly when the task is complete.\`;
+
+/* ============================================================
+ * NODES
+ * ============================================================ */
+
+/**
+ * Classify the user's request and determine if tools are needed
+ *
+ * @flowWeaver nodeType
+ * @label Classify
+ * @color purple
+ * @icon psychology
+ * @input execute [order:0] - Execute
+ * @input userMessage [order:1] - User's input message
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ * @output content [order:2] - LLM response text
+ * @output toolCalls [order:3] - Tool calls requested by LLM
+ * @output hasToolCalls [order:4] - Whether LLM wants to call tools
+ * @output messages [order:5] - Updated conversation messages
+ */
+async function classify(
+  execute: boolean,
+  userMessage: string
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  content: string | null;
+  toolCalls: LLMToolCall[];
+  hasToolCalls: boolean;
+  messages: LLMMessage[];
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, content: null, toolCalls: [], hasToolCalls: false, messages: [] };
+  }
+
+  try {
+    const messages: LLMMessage[] = [{ role: 'user', content: userMessage }];
+    const response = await llmProvider.chat(messages, {
+      tools: AVAILABLE_TOOLS,
+      systemPrompt: SYSTEM_PROMPT,
+    });
+
+    return {
+      onSuccess: true,
+      onFailure: false,
+      content: response.content,
+      toolCalls: response.toolCalls,
+      hasToolCalls: response.toolCalls.length > 0,
+      messages: [
+        ...messages,
+        { role: 'assistant', content: response.content || '' },
+      ],
+    };
+  } catch {
+    return { onSuccess: false, onFailure: true, content: null, toolCalls: [], hasToolCalls: false, messages: [] };
+  }
+}
+
+/**
+ * Execute tool calls from the LLM response
+ *
+ * @flowWeaver nodeType
+ * @label Execute Tools
+ * @color cyan
+ * @icon build
+ * @input execute [order:0] - Execute
+ * @input toolCalls [order:1] - Tool calls to execute
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ * @output results [order:2] - Tool execution results as messages
+ */
+async function executeTool(
+  execute: boolean,
+  toolCalls: LLMToolCall[]
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  results: LLMMessage[];
+}> {
+  if (!execute || !toolCalls || toolCalls.length === 0) {
+    return { onSuccess: true, onFailure: false, results: [] };
+  }
+
+  const results: LLMMessage[] = [];
+
+  for (const call of toolCalls) {
+    const impl = TOOL_IMPLEMENTATIONS[call.name];
+    if (!impl) {
+      results.push({ role: 'tool', content: 'Unknown tool: ' + call.name, toolCallId: call.id });
+      continue;
+    }
+
+    const result = await impl(call.arguments);
+    results.push({
+      role: 'tool',
+      content: result.ok ? result.value : 'Error: ' + result.error,
+      toolCallId: call.id,
+    });
+  }
+
+  return { onSuccess: true, onFailure: false, results };
+}
+
+/**
+ * Request human approval before proceeding
+ *
+ * @flowWeaver nodeType
+ * @label Request Approval
+ * @color orange
+ * @icon verified
+ * @input execute [order:0] - Execute
+ * @input toolResults [order:1] - Tool results to review
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure (rejected or timeout)
+ * @output approved [order:2] - Whether the request was approved
+ */
+async function approvalGate(
+  execute: boolean,
+  toolResults: LLMMessage[]
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  approved: boolean;
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, approved: false };
+  }
+
+  try {
+    const summary = toolResults.map((m) => m.content).join('; ');
+    const result = await requestApproval(
+      'Review tool execution results before responding to user',
+      { toolResults: summary }
+    );
+
+    if (!result.approved) {
+      return { onSuccess: false, onFailure: true, approved: false };
+    }
+
+    return { onSuccess: true, onFailure: false, approved: true };
+  } catch {
+    return { onSuccess: false, onFailure: true, approved: false };
+  }
+}
+
+/**
+ * Generate the final response incorporating tool results
+ *
+ * @flowWeaver nodeType
+ * @label Respond
+ * @color purple
+ * @icon psychology
+ * @input execute [order:0] - Execute
+ * @input messages [order:1] - Conversation history including tool results
+ * @input toolResults [order:2] - Tool result messages to append
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ * @output response [order:2] - Final response text
+ */
+async function respond(
+  execute: boolean,
+  messages: LLMMessage[],
+  toolResults: LLMMessage[]
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  response: string;
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, response: '' };
+  }
+
+  try {
+    const fullMessages = [...messages, ...toolResults];
+    const result = await llmProvider.chat(fullMessages, {
+      systemPrompt: SYSTEM_PROMPT,
+    });
+
+    return {
+      onSuccess: true,
+      onFailure: false,
+      response: result.content || 'No response generated',
+    };
+  } catch {
+    return { onSuccess: false, onFailure: true, response: '' };
+  }
+}
+
+/* ============================================================
+ * WORKFLOW
+ * ============================================================ */
+
+/**
+ * Durable AI Agent — linear pipeline with tool calling and human approval.
+ * Each node becomes a checkpointed step when compiled to Inngest.
+ *
+ * @flowWeaver workflow
+ * @trigger event="agent/request"
+ * @retries 3
+ * @node cls classify
+ * @node tools executeTool
+ * @node approval approvalGate
+ * @node resp respond
+ * @position Start -500 0
+ * @position cls -280 0
+ * @position tools -40 0
+ * @position approval 200 0
+ * @position resp 440 0
+ * @position Exit 680 0
+ * @connect Start.execute -> cls.execute
+ * @connect Start.userMessage -> cls.userMessage
+ * @connect cls.onSuccess -> tools.execute
+ * @connect cls.toolCalls -> tools.toolCalls
+ * @connect tools.onSuccess -> approval.execute
+ * @connect tools.results -> approval.toolResults
+ * @connect approval.onSuccess -> resp.execute
+ * @connect cls.messages -> resp.messages
+ * @connect tools.results -> resp.toolResults
+ * @connect cls.onFailure -> Exit.onFailure
+ * @connect resp.onSuccess -> Exit.onSuccess
+ * @connect resp.response -> Exit.response
+ * @param execute [order:0] - Execute
+ * @param userMessage [order:1] - User's message to the agent
+ * @returns onSuccess [order:0] - Agent completed successfully
+ * @returns onFailure [order:1] - Agent encountered an error
+ * @returns response [order:2] - Agent's final response
+ */
+export async function ${workflowName}(
+  execute: boolean,
+  params: { userMessage: string }
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  response: string;
+}> {
+  throw new Error('Compile with: flow-weaver compile <file>');
+}
+`.trim();
+    },
+};
+//# sourceMappingURL=ai-agent-durable.js.map

package/dist/cli/templates/workflows/ai-agent.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AI Agent Template
+ * Stateful, tool-calling agent with explicit loop and termination semantics
+ */
+import type { WorkflowTemplate } from '../index.js';
+/** Shared configSchema for AI templates */
+export declare const aiConfigSchema: {
+    provider: {
+        type: "select";
+        label: string;
+        description: string;
+        default: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+    };
+    model: {
+        type: "string";
+        label: string;
+        description: string;
+        default: string;
+        placeholder: string;
+        dependsOn: {
+            field: string;
+            values: string[];
+        };
+    };
+};
+export declare const aiAgentTemplate: WorkflowTemplate;
+//# sourceMappingURL=ai-agent.d.ts.map

package/dist/cli/templates/workflows/ai-agent.js

@@ -0,0 +1,326 @@
+import { getProviderCode } from '../providers/index.js';
+import { LLM_CORE_TYPES, LLM_MOCK_PROVIDER_WITH_TOOLS } from '../shared/llm-types.js';
+/** Shared configSchema for AI templates */
+export const aiConfigSchema = {
+    provider: {
+        type: 'select',
+        label: 'LLM Provider',
+        description: 'Choose your LLM provider',
+        default: 'mock',
+        options: [
+            { value: 'openai', label: 'OpenAI' },
+            { value: 'anthropic', label: 'Anthropic' },
+            { value: 'ollama', label: 'Ollama (Local)' },
+            { value: 'mock', label: 'Mock (Testing)' },
+        ],
+    },
+    model: {
+        type: 'string',
+        label: 'Model',
+        description: 'Model identifier',
+        default: 'gpt-4o',
+        placeholder: 'e.g., gpt-4o, claude-3-5-sonnet-20241022, llama3.2',
+        dependsOn: {
+            field: 'provider',
+            values: ['openai', 'anthropic', 'ollama'],
+        },
+    },
+};
+export const aiAgentTemplate = {
+    id: 'ai-agent',
+    name: 'AI Agent (Tool Calling)',
+    description: 'Stateful LLM agent with explicit reasoning loop and tool execution',
+    category: 'ai',
+    configSchema: aiConfigSchema,
+    generate: ({ workflowName, config }) => {
+        const provider = config?.provider || 'mock';
+        const model = config?.model || '';
+        // Get provider-specific code or use mock
+        const providerCode = provider === 'mock'
+            ? `
+/* ============================================================
+ * MOCK PROVIDER (REPLACE IN REAL USE)
+ * ============================================================
+ */
+
+${LLM_MOCK_PROVIDER_WITH_TOOLS}
+`
+            : getProviderCode(provider, model);
+        return `
+/* ============================================================
+ * CORE TYPES
+ * ============================================================
+ */
+
+${LLM_CORE_TYPES}
+
+type TerminationReason =
+  | 'completed'
+  | 'max_iterations'
+  | 'tool_error'
+  | 'llm_error'
+  | 'aborted';
+
+/* ============================================================
+ * AGENT STATE
+ * ============================================================
+ */
+
+interface AgentState {
+  messages: LLMMessage[];
+  iteration: number;
+  toolsUsed: string[];
+  terminated: boolean;
+  terminationReason?: TerminationReason;
+  finalResponse?: string;
+}
+
+${providerCode}
+
+const SYSTEM_PROMPT = \`You are a helpful AI assistant with access to tools.
+Use tools when necessary. Respond directly when the task is complete.\`;
+
+const MAX_ITERATIONS = 10;
+
+/* ============================================================
+ * TOOLS
+ * ============================================================
+ */
+
+const AVAILABLE_TOOLS: LLMTool[] = [
+  {
+    name: 'search',
+    description: 'Search for information',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+type ToolResult =
+  | { ok: true; value: string }
+  | { ok: false; error: string };
+
+type ToolFn = (args: Record<string, unknown>) => Promise<ToolResult>;
+
+const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
+  async search(args) {
+    if (typeof args.query !== 'string') {
+      return { ok: false, error: 'Invalid query' };
+    }
+    return { ok: true, value: '[Search results for: ' + args.query + ']' };
+  },
+};
+
+/* ============================================================
+ * NODES
+ * ============================================================
+ */
+
+/**
+ * Agent loop that orchestrates LLM calls and tool execution
+ * Uses scoped ports to handle iteration internally
+ *
+ * @flowWeaver nodeType
+ * @label Agent Loop
+ * @input userMessage [order:1] - User's input message
+ * @input success scope:iteration [order:0] - From LLM onSuccess
+ * @input failure scope:iteration [order:1] - From LLM onFailure
+ * @input llmResponse scope:iteration [order:2] - LLM response
+ * @input toolMessages scope:iteration [order:3] - Tool results
+ * @input execute [order:0] - Execute
+ * @output start scope:iteration [order:0] - Triggers iteration
+ * @output state scope:iteration [order:1] - Current agent state
+ * @output response [order:2] - Final response when done
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+async function agentLoop(
+  execute: boolean,
+  userMessage: string,
+  iteration: (start: boolean, state: AgentState) => Promise<{
+    success: boolean;
+    failure: boolean;
+    llmResponse: LLMResponse | null;
+    toolMessages: LLMMessage[];
+  }>
+): Promise<{ onSuccess: boolean; onFailure: boolean; response: string }> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, response: '' };
+  }
+
+  let state: AgentState = {
+    messages: [{ role: 'user', content: userMessage }],
+    iteration: 0,
+    toolsUsed: [],
+    terminated: false,
+  };
+
+  while (state.iteration < MAX_ITERATIONS) {
+    const result = await iteration(true, state);
+
+    state.iteration++;
+
+    // Handle LLM failure
+    if (result.failure) {
+      return { onSuccess: false, onFailure: true, response: 'LLM error occurred' };
+    }
+
+    // Add assistant message if present
+    if (result.llmResponse?.content) {
+      state.messages.push({ role: 'assistant', content: result.llmResponse.content });
+    }
+
+    // Add tool messages
+    if (result.toolMessages && result.toolMessages.length > 0) {
+      state.messages.push(...result.toolMessages);
+    }
+
+    // Check termination: no tool calls means we're done
+    if (result.llmResponse && result.llmResponse.toolCalls.length === 0 && result.llmResponse.content) {
+      return { onSuccess: true, onFailure: false, response: result.llmResponse.content };
+    }
+  }
+
+  return { onSuccess: true, onFailure: false, response: 'Max iterations reached' };
+}
+
+/**
+ * Calls the LLM with current state
+ *
+ * @flowWeaver nodeType
+ * @label Call LLM
+ * @input state [order:1] - Current agent state
+ * @input execute [order:0] - Execute
+ * @output response [order:2] - LLM response
+ * @output toolCalls [order:3] - Tool calls from LLM
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+async function callLLM(
+  execute: boolean,
+  state: AgentState
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  response: LLMResponse | null;
+  toolCalls: LLMToolCall[];
+}> {
+  if (!execute) {
+    return { onSuccess: false, onFailure: false, response: null, toolCalls: [] };
+  }
+
+  try {
+    const response = await llmProvider.chat(state.messages, {
+      tools: AVAILABLE_TOOLS,
+      systemPrompt: SYSTEM_PROMPT,
+    });
+
+    return { onSuccess: true, onFailure: false, response, toolCalls: response.toolCalls };
+  } catch {
+    return { onSuccess: false, onFailure: true, response: null, toolCalls: [] };
+  }
+}
+
+/**
+ * Executes tool calls
+ *
+ * @flowWeaver nodeType
+ * @label Execute Tools
+ * @input calls [order:1] - Tool calls to execute
+ * @input execute [order:0] - Execute
+ * @output messages [order:2] - Tool response messages
+ * @output onSuccess [order:0] - On Success
+ * @output onFailure [order:1] - On Failure
+ */
+async function executeTools(
+  execute: boolean,
+  calls: LLMToolCall[]
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  messages: LLMMessage[];
+}> {
+  if (!execute || !calls || calls.length === 0) {
+    return { onSuccess: true, onFailure: false, messages: [] };
+  }
+
+  const messages: LLMMessage[] = [];
+
+  for (const call of calls) {
+    const impl = TOOL_IMPLEMENTATIONS[call.name];
+    if (!impl) {
+      messages.push({
+        role: 'tool',
+        content: 'Unknown tool: ' + call.name,
+        toolCallId: call.id,
+      });
+      continue;
+    }
+
+    const result = await impl(call.arguments);
+
+    messages.push({
+      role: 'tool',
+      content: result.ok ? result.value : 'Error: ' + result.error,
+      toolCallId: call.id,
+    });
+  }
+
+  return { onSuccess: true, onFailure: false, messages };
+}
+
+/* ============================================================
+ * WORKFLOW
+ * ============================================================
+ */
+
+/**
+ * AI Agent that uses tools to accomplish tasks
+ *
+ * @flowWeaver workflow
+ * @node loop agentLoop [size: 450 350]
+ * @node llm callLLM loop.iteration
+ * @node tools executeTools loop.iteration
+ * @position Start -450 0
+ * @position loop -180 0
+ * @position llm -40 100
+ * @position tools 120 200
+ * @position Exit 360 0
+ * @connect Start.execute -> loop.execute
+ * @connect Start.userMessage -> loop.userMessage
+ * @connect loop.start:iteration -> llm.execute
+ * @connect loop.state:iteration -> llm.state
+ * @connect llm.toolCalls -> tools.calls
+ * @connect llm.onSuccess -> tools.execute
+ * @connect llm.response -> loop.llmResponse:iteration
+ * @connect llm.onSuccess -> loop.success:iteration
+ * @connect llm.onFailure -> loop.failure:iteration
+ * @connect tools.messages -> loop.toolMessages:iteration
+ * @connect loop.response -> Exit.response
+ * @connect loop.onSuccess -> Exit.onSuccess
+ * @connect loop.onFailure -> Exit.onFailure
+ * @param execute [order:0] - Execute
+ * @param userMessage [order:1] - User's message to the agent
+ * @returns onSuccess [order:0] - Agent completed successfully
+ * @returns onFailure [order:1] - Agent encountered an error
+ * @returns response [order:2] - Agent's final response
+ */
+export async function ${workflowName}(
+  execute: boolean,
+  params: { userMessage: string }
+): Promise<{
+  onSuccess: boolean;
+  onFailure: boolean;
+  response: string;
+}> {
+  throw new Error('Compile with: flow-weaver compile <file>');
+}
+`.trim();
+    },
+};
+//# sourceMappingURL=ai-agent.js.map

package/dist/cli/templates/workflows/ai-chat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stateful Chat Template
+ * Maintains conversation history with memory
+ */
+import type { WorkflowTemplate } from '../index.js';
+export declare const aiChatTemplate: WorkflowTemplate;
+//# sourceMappingURL=ai-chat.d.ts.map