beddel 0.2.3 → 1.0.0

package/src/primitives/llm.ts

@@ -0,0 +1,210 @@
+/**
+ * Beddel Protocol - LLM Primitive
+ * 
+ * Core primitive for AI text generation with dual-mode support:
+ * - Stream Mode: Uses streamText → returns Response via toUIMessageStreamResponse()
+ * - Block Mode: Uses generateText → returns JSON object { text, usage }
+ * 
+ * Supports tools via mapTools() which bridges YAML definitions to Vercel AI SDK tools.
+ * Requires GEMINI_API_KEY environment variable.
+ * 
+ * Server-only: Uses Vercel AI SDK Core which requires Node.js.
+ * 
+ * AI SDK v6 Compatibility:
+ * - Frontend (useChat) sends UIMessage[] with { parts: [...] } format
+ * - Backend (streamText/generateText) expects ModelMessage[] with { content: ... }
+ * - convertToModelMessages() bridges this gap automatically
+ */
+
+import {
+    streamText,
+    generateText,
+    dynamicTool,
+    stepCountIs,
+    convertToModelMessages,
+    type ModelMessage,
+    type UIMessage,
+    type ToolSet,
+} from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import type { StepConfig, ExecutionContext, PrimitiveHandler } from '../types';
+import { toolRegistry, type ToolImplementation } from '../tools';
+import { resolveVariables } from '../core/variable-resolver';
+
+/**
+ * Callback function type for lifecycle hooks (onFinish, onError).
+ */
+export type CallbackFn = (payload: Record<string, unknown>) => void | Promise<void>;
+
+/**
+ * Registry for consumer-registered callbacks.
+ * Populated by the application using Beddel.
+ */
+export const callbackRegistry: Record<string, CallbackFn> = {};
+
+/**
+ * Register a callback function for lifecycle hooks.
+ * 
+ * @param name - Unique identifier for the callback
+ * @param callback - Function to execute when hook is triggered
+ * 
+ * @example
+ * registerCallback('persistConversation', async ({ text, usage }) => {
+ *   await db.saveMessage(text, usage);
+ * });
+ */
+export function registerCallback(name: string, callback: CallbackFn): void {
+    if (callbackRegistry[name]) {
+        console.warn(`[Beddel] Callback '${name}' already registered, overwriting.`);
+    }
+    callbackRegistry[name] = callback;
+}
+
+
+
+/**
+ * Tool definition from YAML config.
+ */
+interface YamlToolDefinition {
+    name: string;
+    description?: string;
+}
+
+/**
+ * LLM step configuration from YAML.
+ */
+interface LlmConfig extends StepConfig {
+    model?: string;
+    stream?: boolean;
+    system?: string;
+    messages?: string | ModelMessage[];
+    tools?: YamlToolDefinition[];
+    onFinish?: string;
+    onError?: string;
+}
+
+/**
+ * Maps YAML tool definitions to Vercel AI SDK tool objects.
+ * 
+ * YAML defines intent (name, optional description override).
+ * Registry provides implementation (parameters, execute).
+ * Uses dynamicTool for flexible type support with unknown input/output types.
+ * 
+ * @param toolDefinitions - Array of tool definitions from YAML config
+ * @returns Record of Vercel AI SDK tools (ToolSet)
+ */
+function mapTools(toolDefinitions: YamlToolDefinition[]): ToolSet {
+    const tools: ToolSet = {};
+
+    for (const def of toolDefinitions) {
+        const impl: ToolImplementation | undefined = toolRegistry[def.name];
+        if (!impl) {
+            console.warn(`[Beddel] Tool '${def.name}' not found in registry, skipping.`);
+            continue;
+        }
+
+        // Use dynamicTool for flexible type handling with registry-defined tools
+        tools[def.name] = dynamicTool({
+            description: def.description || impl.description, // YAML can override
+            inputSchema: impl.parameters,
+            execute: async (args: unknown) => {
+                return impl.execute(args as Record<string, unknown>);
+            },
+        });
+    }
+
+    return tools;
+}
+
+/**
+ * LLM Primitive Handler
+ * 
+ * Dual-mode support via config.stream:
+ * - stream: true → Uses streamText → returns result.toUIMessageStreamResponse()
+ * - stream: false → Uses generateText → returns { text, usage }
+ * 
+ * When tools are present, stopWhen is set to stepCountIs(5) to enable tool loops.
+ * 
+ * AI SDK v6: Converts UIMessage[] (from useChat) to ModelMessage[] automatically.
+ * 
+ * @param config - Step configuration from YAML (model, stream, system, messages, tools)
+ * @param context - Execution context with input and variables
+ * @returns Response (streaming) or Record (blocking mode)
+ */
+export const llmPrimitive: PrimitiveHandler = async (
+    config: StepConfig,
+    context: ExecutionContext
+): Promise<Response | Record<string, unknown>> => {
+    const llmConfig = config as LlmConfig;
+
+    // Initialize Google Generative AI provider
+    const google = createGoogleGenerativeAI({
+        apiKey: process.env.GEMINI_API_KEY,
+    });
+    const model = google(llmConfig.model || 'gemini-1.5-flash');
+
+    // Resolve messages from context (e.g., $input.messages)
+    // AI SDK v6: Frontend sends UIMessage[], we convert to ModelMessage[]
+    const rawMessages = resolveVariables(llmConfig.messages, context) as UIMessage[];
+    const messages = await convertToModelMessages(rawMessages);
+
+    // Map YAML tools to Vercel AI SDK format
+    const hasTools = llmConfig.tools && llmConfig.tools.length > 0;
+    const tools = hasTools ? mapTools(llmConfig.tools!) : undefined;
+
+    if (llmConfig.stream) {
+        // STREAMING MODE: Returns HTTP response directly
+        const result = streamText({
+            model,
+            messages,
+            system: llmConfig.system,
+            // Enable tool loop if tools exist (default is stepCountIs(1))
+            stopWhen: hasTools ? stepCountIs(5) : undefined,
+            tools,
+            // Lifecycle hooks (AI SDK v6 signature)
+            onFinish: async ({ text, finishReason, usage, totalUsage, steps, response }) => {
+                if (llmConfig.onFinish) {
+                    const callback = callbackRegistry[llmConfig.onFinish];
+                    if (callback) {
+                        await callback({
+                            text,
+                            finishReason,
+                            usage,
+                            totalUsage,
+                            steps,
+                            response,
+                        });
+                    }
+                }
+            },
+            onError: ({ error }) => {
+                if (llmConfig.onError) {
+                    const callback = callbackRegistry[llmConfig.onError];
+                    if (callback) {
+                        callback({ error });
+                    }
+                }
+                console.error('[Beddel] Stream error:', error);
+            },
+        });
+
+        // Return streaming response - Executor will detect this and return to client immediately
+        // AI SDK v6: toUIMessageStreamResponse() for useChat compatibility
+        return result.toUIMessageStreamResponse();
+    } else {
+        // BLOCKING MODE: Returns data for next workflow step
+        const result = await generateText({
+            model,
+            messages,
+            system: llmConfig.system,
+            // Enable tool loop if tools exist (default is stepCountIs(1))
+            stopWhen: hasTools ? stepCountIs(5) : undefined,
+            tools,
+        });
+
+        return {
+            text: result.text,
+            usage: result.usage,
+        };
+    }
+};

package/src/primitives/output.ts

@@ -0,0 +1,65 @@
+/**
+ * Beddel Protocol - Output Primitive
+ * 
+ * Deterministic JSON transform primitive for the workflow engine.
+ * Resolves variable references in a template and returns the result.
+ * 
+ * This is a pure transform - no LLM invocation.
+ * 
+ * Server-only: Used within WorkflowExecutor during step execution.
+ */
+
+import type { StepConfig, ExecutionContext, PrimitiveHandler } from '../types';
+import { resolveVariables } from '../core/variable-resolver';
+
+/**
+ * Output step configuration from YAML.
+ */
+interface OutputConfig extends StepConfig {
+    /**
+     * JSON template with variable references to resolve.
+     * 
+     * @example
+     * template:
+     *   status: "completed"
+     *   tokens: "$llmOutput.usage"
+     *   user: "$input.user.name"
+     */
+    template: unknown;
+}
+
+/**
+ * Output Primitive Handler
+ * 
+ * Resolves all variable references in the template and returns
+ * the transformed object for consumption by subsequent steps.
+ * 
+ * Supported patterns (via resolveVariables):
+ * - $input.* → context.input[path]
+ * - $stepResult.* → context.variables.get(stepName)[path]
+ * - $varName.* → context.variables.get(varName)[path] (legacy)
+ * 
+ * @param config - Step configuration from YAML (must contain 'template')
+ * @param context - Execution context with input and variables
+ * @returns Resolved template as Record (never streams)
+ */
+export const outputPrimitive: PrimitiveHandler = async (
+    config: StepConfig,
+    context: ExecutionContext
+): Promise<Record<string, unknown>> => {
+    const outputConfig = config as OutputConfig;
+
+    if (outputConfig.template === undefined) {
+        console.warn('[Beddel] output-generator: No template provided, returning empty object.');
+        return {};
+    }
+
+    const resolved = resolveVariables(outputConfig.template, context);
+
+    // Ensure we return a Record even if template resolves to primitive
+    if (typeof resolved !== 'object' || resolved === null) {
+        return { value: resolved };
+    }
+
+    return resolved as Record<string, unknown>;
+};

package/src/server/handler.ts

@@ -0,0 +1,80 @@
+import { NextRequest } from 'next/server';
+import { loadYaml } from '../core/parser';
+import { WorkflowExecutor } from '../core/workflow';
+import { join, normalize } from 'path';
+
+export interface BeddelHandlerOptions {
+    agentsPath?: string;
+}
+
+export type BeddelHandler = (request: NextRequest) => Promise<Response>;
+
+/**
+ * Validate agentId to prevent path traversal attacks.
+ * Only allows alphanumeric characters, hyphens, and underscores.
+ * 
+ * @param agentId - The agent identifier from request
+ * @returns true if valid, false otherwise
+ */
+function isValidAgentId(agentId: string): boolean {
+    // Must be non-empty string
+    if (typeof agentId !== 'string' || agentId.length === 0) {
+        return false;
+    }
+    
+    // Only allow safe characters: alphanumeric, hyphen, underscore
+    // No dots, slashes, or other path characters
+    const safePattern = /^[a-zA-Z0-9_-]+$/;
+    
+    return safePattern.test(agentId);
+}
+
+export function createBeddelHandler(options: BeddelHandlerOptions = {}): BeddelHandler {
+    const agentsPath = options.agentsPath || 'src/agents';
+
+    return async function POST(request: NextRequest): Promise<Response> {
+        try {
+            const body = await request.json() as any;
+            const { agentId, ...input } = body;
+
+            if (!agentId) {
+                return Response.json({ error: 'agentId is required' }, { status: 400 });
+            }
+
+            // Security: Validate agentId to prevent path traversal
+            if (!isValidAgentId(agentId)) {
+                return Response.json(
+                    { error: 'Invalid agentId: only alphanumeric characters, hyphens, and underscores allowed' },
+                    { status: 400 }
+                );
+            }
+
+            // Resolve path relative to CWD (usually project root)
+            const basePath = join(process.cwd(), agentsPath);
+            const fullPath = normalize(join(basePath, `${agentId}.yaml`));
+            
+            // Double-check: ensure resolved path is within agents directory
+            if (!fullPath.startsWith(basePath)) {
+                return Response.json({ error: 'Invalid agentId' }, { status: 400 });
+            }
+            
+            const yaml = await loadYaml(fullPath);
+
+            const executor = new WorkflowExecutor(yaml);
+            // Pass the entire body (minus agentId) as input ($input)
+            const result = await executor.execute(input);
+
+            if (result instanceof Response) {
+                return result;
+            }
+
+            return Response.json(result);
+        } catch (error) {
+            console.error('[Beddel] Handler Error:', error);
+            return Response.json(
+                { error: error instanceof Error ? error.message : 'Internal Server Error' },
+                { status: 500 }
+            );
+        }
+    };
+}

package/src/server.ts

@@ -0,0 +1,10 @@
+/**
+ * Beddel Protocol - Server Entry Point
+ * 
+ * Use: import { createBeddelHandler } from 'beddel/server'
+ * 
+ * This module provides the server-side handler factory for Next.js API routes.
+ * Contains Node.js dependencies - DO NOT import in client code.
+ */
+
+export { createBeddelHandler, type BeddelHandlerOptions } from './server/handler';

package/src/tools/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Beddel Protocol - Tool Registry
+ * 
+ * This registry contains tool implementations that LLM primitives can access.
+ * Each tool has: description, Zod parameters schema, and execute function.
+ * 
+ * Following Expansion Pack Pattern from BMAD-METHOD™ for extensibility.
+ * See: https://github.com/bmadcode/bmad-method
+ */
+
+import { z } from 'zod';
+
+/**
+ * Interface for tool implementations in the registry.
+ * Tools are invoked by the LLM via function calling.
+ */
+export interface ToolImplementation {
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** Zod schema defining the tool's input parameters */
+    parameters: z.ZodSchema;
+    /** Async function that executes the tool and returns results */
+    execute: (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Registry of available tools keyed by tool name.
+ * 
+ * YAML workflows reference tools by name:
+ * ```yaml
+ * tools:
+ *   - name: "calculator"
+ *     description: "Optional override" # Can override default description
+ * ```
+ */
+export const toolRegistry: Record<string, ToolImplementation> = {
+    /**
+     * Calculator tool - evaluates mathematical expressions safely.
+     * 
+     * Security: Only allows numbers, operators (+, -, *, /, %, **), 
+     * parentheses, and decimal points. No function calls or variables.
+     * 
+     * @example
+     * Input: { expression: "2 + 2 * 3" }
+     * Output: { result: 8 }
+     */
+    calculator: {
+        description: 'Evaluate a mathematical expression (numbers and basic operators only)',
+        parameters: z.object({
+            expression: z.string().describe('The math expression to evaluate (e.g., "2 + 2 * 3")'),
+        }),
+        execute: async ({ expression }) => {
+            const expr = String(expression);
+            
+            // Security: Whitelist only safe characters
+            // Allows: digits, operators, parentheses, spaces, decimal points
+            const safePattern = /^[\d\s+\-*/%().]+$/;
+            
+            if (!safePattern.test(expr)) {
+                return { error: 'Invalid expression: only numbers and operators (+, -, *, /, %, **) allowed' };
+            }
+            
+            // Additional check: no empty parentheses or dangerous patterns
+            if (/\(\s*\)/.test(expr) || /[a-zA-Z_$]/.test(expr)) {
+                return { error: 'Invalid expression: function calls not allowed' };
+            }
+            
+            try {
+                // Safe to evaluate after whitelist validation
+                const result = Function(`"use strict"; return (${expr})`)();
+                
+                if (typeof result !== 'number' || !Number.isFinite(result)) {
+                    return { error: 'Expression did not evaluate to a valid number' };
+                }
+                
+                return { result };
+            } catch (e) {
+                return { error: `Evaluation failed: ${e instanceof Error ? e.message : 'unknown error'}` };
+            }
+        },
+    },
+
+    /**
+     * getCurrentTime tool - returns current date and time in ISO format.
+     * 
+     * @example
+     * Input: {}
+     * Output: { time: "2024-12-23T15:30:00.000Z" }
+     */
+    getCurrentTime: {
+        description: 'Get the current date and time in ISO format',
+        parameters: z.object({}),
+        execute: async () => {
+            return { time: new Date().toISOString() };
+        },
+    },
+};
+
+/**
+ * Register a custom tool in the registry.
+ * Allows consumers to extend Beddel with domain-specific tools.
+ * 
+ * @param name - Unique identifier for the tool
+ * @param implementation - Tool implementation object
+ * 
+ * @example
+ * registerTool('weatherLookup', {
+ *   description: 'Get weather for a city',
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => fetchWeather(city),
+ * });
+ */
+export function registerTool(name: string, implementation: ToolImplementation): void {
+    if (toolRegistry[name]) {
+        console.warn(`[Beddel] Tool '${name}' already registered, overwriting.`);
+    }
+    toolRegistry[name] = implementation;
+}

package/src/types/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Beddel Protocol - Type Definitions
+ * Core interfaces for the workflow engine
+ */
+
+/**
+ * Metadata from YAML header section
+ */
+export interface YamlMetadata {
+    name: string;
+    version: string;
+}
+
+/**
+ * Configuration for a workflow step
+ * Contents vary by step type (llm, output-generator, call-agent)
+ */
+export interface StepConfig {
+    [key: string]: unknown;
+}
+
+/**
+ * Individual workflow step definition
+ */
+export interface WorkflowStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Step type: 'llm' | 'output-generator' | 'call-agent' */
+    type: string;
+    /** Step-specific configuration */
+    config: StepConfig;
+    /** Optional variable name to store step result */
+    result?: string;
+}
+
+/**
+ * Complete parsed YAML document structure
+ */
+export interface ParsedYaml {
+    metadata: YamlMetadata;
+    workflow: WorkflowStep[];
+}
+
+/**
+ * Execution context passed to primitive handlers
+ * Holds input data and accumulated step results
+ */
+export interface ExecutionContext {
+    /** Original input passed to WorkflowExecutor.execute() */
+    input: unknown;
+    /** Map of step results keyed by step.result name */
+    variables: Map<string, unknown>;
+}
+
+/**
+ * Contract for primitive handlers (llm, output-generator, call-agent)
+ * Handlers may return Response (streaming) or Record (data for next step)
+ */
+export type PrimitiveHandler = (
+    config: StepConfig,
+    context: ExecutionContext
+) => Promise<Response | Record<string, unknown>>;

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": [
+            "ES2022"
+        ],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "declaration": true,
+        "declarationMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "resolveJsonModule": true,
+        "isolatedModules": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}

package/CHANGELOG.md

@@ -1,78 +0,0 @@
-# Changelog
-
-## [0.2.3] - 2025-12-20
-
-### Added
-- **Client-Safe Type Exports**: Exposed shared types for frontend consumption
-  - `AgentMetadata`, `AgentResponse`, `ExecutionStep` from shared agent types
-  - `WorkflowStepType`, `AgentCategory` for workflow typing
-  - `ChatHandlerParams`, `ChatHandlerResult`, `ChatMetadata` for chat agent
-  - `ConversationMessage` from RAG types
-  - `chatMetadata` constant for chat agent metadata
-
-### Purpose
-- Enable frontend applications to import types directly from `beddel` package
-- Support type-safe chat UI development without duplicating type definitions
-- All exported types are client-safe (no server-only dependencies)
-
-## [0.2.2] - 2025-12-19
-
-### Changed
-- Maintenance release (no functional changes)
-
-## [0.2.0] - 2025-12-18
-
-### Added
-- **TypeScript Code-Behind for Custom Agents**: Custom agents can now include TypeScript implementations alongside YAML definitions
-  - Place `.ts` files in `/agents` directory
-  - Export functions are automatically registered with namespaced keys
-  - New `custom-action` workflow type for executing TypeScript functions
-  - Full access to input, variables, execution context, and Beddel helpers
-- **Enhanced Agent Registry**: 
-  - `loadCustomFunctions()` method for dynamic TypeScript module loading
-  - `getCustomFunction()` method for runtime function retrieval
-  - Async agent loading with proper error handling
-- **Complete Documentation**: Added comprehensive guide for TypeScript code-behind in README.md
-
-### Changed
-- `AgentRegistry.loadCustomAgents()` is now async to support dynamic imports
-- Updated agent loading flow to include TypeScript module discovery
-
-### Backward Compatibility
-- All existing agents (joker, translator, image-generator) continue to work without changes
-- YAML-only agents are fully supported
-- No breaking changes to existing APIs
-
----
-
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.1.0] - 2025-12-18
-
-### Added
-- Initial release of Beddel package
-- Secure YAML parser with FAILSAFE schema
-- Declarative agent runtime (protocol v2.0)
-- Agent registry with custom agent support
-- Built-in agents: joker, translator, image generator
-- Schema validation with Zod
-- Isolated runtime with security profiles
-- Multi-tenant Firebase support
-- GDPR/LGPD compliance utilities
-- Performance monitoring and autoscaling
-- Security scanning and threat detection
-- Server utilities (KV store, runtime security)
-- GraphQL API integration
-- Comprehensive documentation and guides
-
-### Features
-- Custom agents auto-discovery from `/agents` directory
-- Agent override mechanism (custom > built-in)
-- Variable interpolation in YAML workflows
-- Nested property access in output schemas
-- Gemini Flash integration for AI capabilities
-- TypeScript support with full type definitions

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Beddel Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/agents/chat/chat.handler.d.ts

@@ -1,12 +0,0 @@
-import 'server-only';
-/**
- * Chat Agent Handler - Server-only execution logic
- * Orchestrates RAG pipeline or simple chat based on mode
- */
-import type { ExecutionContext } from '../../types/executionContext';
-import type { ChatHandlerParams, ChatHandlerResult } from './chat.types';
-/**
- * Execute chat orchestration
- */
-export declare function executeChatHandler(params: ChatHandlerParams, props: Record<string, string>, context: ExecutionContext): Promise<ChatHandlerResult>;
-//# sourceMappingURL=chat.handler.d.ts.map

package/dist/agents/chat/chat.handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chat.handler.d.ts","sourceRoot":"","sources":["../../../src/agents/chat/chat.handler.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAErB;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAY,MAAM,cAAc,CAAC;AAqKnF;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}