beddel 0.2.3 → 1.0.0

package/dist/primitives/index.js

@@ -0,0 +1,72 @@
+/**
+ * Beddel Protocol - Primitive Handler Registry
+ *
+ * This registry maps step types to their handler implementations.
+ * Following Expansion Pack Pattern from BMAD-METHOD™ for extensibility.
+ * See: https://github.com/bmadcode/bmad-method
+ *
+ * Server-only: Handlers may use Node.js APIs and external services.
+ */
+import { llmPrimitive } from './llm';
+import { outputPrimitive } from './output';
+// Re-export llm exports for consumer access
+export { llmPrimitive, registerCallback, callbackRegistry } from './llm';
+/**
+ * Placeholder handler for primitives not yet implemented.
+ * Returns config and context for debugging purposes.
+ */
+const placeholderHandler = async (config, context) => {
+    console.warn('[Beddel] Placeholder handler invoked. Implement the actual primitive.');
+    return {
+        _placeholder: true,
+        config,
+        input: context.input,
+        variableCount: context.variables.size,
+    };
+};
+/**
+ * Registry of primitive handlers keyed by step type.
+ *
+ * MVP Primitives:
+ * - 'llm': Wrapper for streamText/generateText (Task 2.2)
+ * - 'output-generator': Deterministic variable mapping (Task 2.3)
+ * - 'call-agent': Sub-agent invocation (future)
+ */
+export const handlerRegistry = {
+    /**
+     * LLM Primitive - Dual-mode AI text generation.
+     * Supports streaming (streamText) and blocking (generateText) modes.
+     */
+    'llm': llmPrimitive,
+    /**
+     * Output Generator Primitive - Deterministic JSON transform.
+     * Resolves variable references in templates.
+     */
+    'output-generator': outputPrimitive,
+    /**
+     * Call Agent Primitive - Placeholder
+     * Enables recursive workflow execution via sub-agents.
+     */
+    'call-agent': placeholderHandler,
+};
+/**
+ * Register a custom primitive handler in the registry.
+ * Allows consumers to extend Beddel with domain-specific primitives.
+ *
+ * @param type - Step type identifier (e.g., 'my-custom-primitive')
+ * @param handler - PrimitiveHandler function
+ *
+ * @example
+ * import { registerPrimitive } from 'beddel';
+ *
+ * registerPrimitive('http-fetch', async (config, context) => {
+ *   const response = await fetch(config.url);
+ *   return { data: await response.json() };
+ * });
+ */
+export function registerPrimitive(type, handler) {
+    if (handlerRegistry[type]) {
+        console.warn(`[Beddel] Primitive '${type}' already registered, overwriting.`);
+    }
+    handlerRegistry[type] = handler;
+}

package/dist/primitives/llm.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 type { PrimitiveHandler } from '../types';
+/**
+ * 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 declare 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 declare function registerCallback(name: string, callback: CallbackFn): void;
+/**
+ * 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 declare const llmPrimitive: PrimitiveHandler;
+//# sourceMappingURL=llm.d.ts.map

package/dist/primitives/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/primitives/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAI/E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAM,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI,CAKzE;AA0DD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,gBA4E1B,CAAC"}

package/dist/primitives/llm.js

@@ -0,0 +1,156 @@
+/**
+ * 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, } from 'ai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { toolRegistry } from '../tools';
+import { resolveVariables } from '../core/variable-resolver';
+/**
+ * Registry for consumer-registered callbacks.
+ * Populated by the application using Beddel.
+ */
+export const callbackRegistry = {};
+/**
+ * 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, callback) {
+    if (callbackRegistry[name]) {
+        console.warn(`[Beddel] Callback '${name}' already registered, overwriting.`);
+    }
+    callbackRegistry[name] = callback;
+}
+/**
+ * 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) {
+    const tools = {};
+    for (const def of toolDefinitions) {
+        const impl = 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) => {
+                return impl.execute(args);
+            },
+        });
+    }
+    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 = async (config, context) => {
+    const llmConfig = config;
+    // 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);
+    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/dist/primitives/output.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { PrimitiveHandler } from '../types';
+/**
+ * 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 declare const outputPrimitive: PrimitiveHandler;
+//# sourceMappingURL=output.d.ts.map

package/dist/primitives/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/primitives/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAmB/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,EAAE,gBAmB7B,CAAC"}

package/dist/primitives/output.js

@@ -0,0 +1,39 @@
+/**
+ * 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 { resolveVariables } from '../core/variable-resolver';
+/**
+ * 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 = async (config, context) => {
+    const outputConfig = config;
+    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;
+};

package/dist/server/handler.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest } from 'next/server';
+export interface BeddelHandlerOptions {
+    agentsPath?: string;
+}
+export type BeddelHandler = (request: NextRequest) => Promise<Response>;
+export declare function createBeddelHandler(options?: BeddelHandlerOptions): BeddelHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/server/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/server/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,MAAM,WAAW,oBAAoB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAsBxE,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAgDrF"}

package/dist/server/handler.js

@@ -0,0 +1,55 @@
+import { loadYaml } from '../core/parser';
+import { WorkflowExecutor } from '../core/workflow';
+import { join, normalize } from 'path';
+/**
+ * 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) {
+    // 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 = {}) {
+    const agentsPath = options.agentsPath || 'src/agents';
+    return async function POST(request) {
+        try {
+            const body = await request.json();
+            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/dist/server.d.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';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/server.js

@@ -0,0 +1,9 @@
+/**
+ * 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 } from './server/handler';

package/dist/tools/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare const toolRegistry: Record<string, ToolImplementation>;
+/**
+ * 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 declare function registerTool(name: string, implementation: ToolImplementation): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CA6D3D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAKnF"}

package/dist/tools/index.js

@@ -0,0 +1,96 @@
+/**
+ * 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';
+/**
+ * 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 = {
+    /**
+     * 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, implementation) {
+    if (toolRegistry[name]) {
+        console.warn(`[Beddel] Tool '${name}' already registered, overwriting.`);
+    }
+    toolRegistry[name] = implementation;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC3B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,gBAAgB,KACxB,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Beddel Protocol - Type Definitions
+ * Core interfaces for the workflow engine
+ */
+export {};