beddel 1.0.2 → 1.0.4

package/README.md

@@ -1,7 +1,7 @@
 # Beddel Protocol
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![npm version](https://img.shields.io/badge/npm-1.0.0-brightgreen.svg)](https://www.npmjs.com/package/beddel)
+[![npm version](https://img.shields.io/badge/npm-1.0.4-brightgreen.svg)](https://www.npmjs.com/package/beddel)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
 [![AI SDK](https://img.shields.io/badge/AI%20SDK-v6-purple.svg)](https://sdk.vercel.ai/)
 
@@ -10,11 +10,12 @@
 ## Features
 
 - 🔄 **Sequential Pipeline Execution** — Define workflows as YAML, execute steps in order
-- 🌊 **Native Streaming** — First-class `streamText` support with `useChat` compatibility
+- 🌊 **Native Streaming** — First-class `streamText` support via `chat` primitive with `useChat` compatibility
 - 🔌 **Extensible Primitives** — Register custom step types, tools, and callbacks
 - 🔒 **Security First** — YAML parsing with `FAILSAFE_SCHEMA` prevents code execution
 - 📦 **Bundle Separation** — Three entry points for server, client, and full API access
-- 🌐 **Multi-Provider** — Built-in support for Google Gemini and Amazon Bedrock
+- 🌐 **Multi-Provider** — Built-in support for Google Gemini, Amazon Bedrock, and OpenRouter (400+ models)
+- 🔀 **Semantic Primitives** — `chat` for streaming frontend, `llm` for blocking workflows
 
 ## Installation
 
@@ -51,11 +52,10 @@ metadata:
 
 workflow:
   - id: "chat-interaction"
-    type: "llm"
+    type: "chat"
     config:
       provider: "google"
       model: "gemini-2.0-flash-exp"
-      stream: true
       system: "You are a helpful assistant."
       messages: "$input.messages"
 ```
@@ -71,17 +71,34 @@ metadata:
 
 workflow:
   - id: "chat"
-    type: "llm"
+    type: "chat"
     config:
       provider: "bedrock"
       model: "us.meta.llama3-2-1b-instruct-v1:0"
-      stream: true
       system: |
         You are a helpful, friendly assistant. Be concise and direct.
         Answer in the same language the user writes to you.
       messages: "$input.messages"
 ```
 
+#### Example 3: OpenRouter (400+ Models)
+
+```yaml
+# src/agents/assistant-openrouter.yaml
+metadata:
+  name: "OpenRouter Assistant"
+  version: "1.0.0"
+
+workflow:
+  - id: "chat"
+    type: "chat"
+    config:
+      provider: "openrouter"
+      model: "qwen/qwen3-14b:free"  # or any model from openrouter.ai/models
+      system: "You are a helpful assistant."
+      messages: "$input.messages"
+```
+
 ### 3. Set Environment Variables
 
 ```bash
@@ -94,6 +111,9 @@ AWS_BEARER_TOKEN_BEDROCK=your_bedrock_api_key
 # Or use standard AWS credentials:
 # AWS_ACCESS_KEY_ID=your_access_key
 # AWS_SECRET_ACCESS_KEY=your_secret_key
+
+# For OpenRouter
+OPENROUTER_API_KEY=your_openrouter_api_key
 ```
 
 ### 4. Use with React (useChat)
@@ -128,6 +148,7 @@ export default function Chat() {
 |----------|----------------------|---------------|
 | `google` | `GEMINI_API_KEY` | `gemini-1.5-flash` |
 | `bedrock` | `AWS_REGION`, `AWS_BEARER_TOKEN_BEDROCK` (or AWS credentials) | `anthropic.claude-3-haiku-20240307-v1:0` |
+| `openrouter` | `OPENROUTER_API_KEY` | `qwen/qwen3-14b:free` |
 
 > **Note:** The Bedrock provider requires `AWS_REGION` to be set (defaults to `us-east-1` if not provided).
 
@@ -188,10 +209,9 @@ metadata:
 
 workflow:
   - id: "step-1"
-    type: "llm"
+    type: "chat"          # or "llm" for non-streaming workflows
     config:
       model: "gemini-2.0-flash-exp"
-      stream: true
       system: "System prompt"
       messages: "$input.messages"
       tools:
@@ -200,6 +220,15 @@ workflow:
     result: "stepOutput"
 ```
 
+### Primitive Types
+
+| Type | Behavior | Use Case |
+|------|----------|----------|
+| `chat` | Always streaming, converts UIMessage | Frontend chat interfaces (`useChat`) |
+| `llm` | Never streaming, returns complete result | Multi-step workflows, variable passing |
+| `call-agent` | Invokes another agent | Sub-agent orchestration |
+| `output-generator` | JSON template transform | Structured output generation |
+
 ### Variable Resolution
 
 | Pattern | Description | Example |
@@ -220,8 +249,9 @@ Beddel is fully compatible with Vercel AI SDK v6:
 
 - **Frontend:** `useChat` sends `UIMessage[]` with `{ parts: [...] }` format
 - **Backend:** `streamText`/`generateText` expects `ModelMessage[]` with `{ content: ... }`
-- **Automatic Conversion:** `convertToModelMessages()` bridges the gap
-- **Streaming:** `toUIMessageStreamResponse()` returns the correct format for `useChat`
+- **Automatic Conversion:** `chat` primitive uses `convertToModelMessages()` to bridge the gap
+- **Streaming:** `chat` primitive returns `toUIMessageStreamResponse()` for `useChat`
+- **Blocking:** `llm` primitive uses `generateText()` for workflow steps
 
 ## Technology Stack
 
@@ -232,6 +262,7 @@ Beddel is fully compatible with Vercel AI SDK v6:
 | AI Core | `ai` | 6.x |
 | AI Provider | `@ai-sdk/google` | 3.x |
 | AI Provider | `@ai-sdk/amazon-bedrock` | 4.x |
+| AI Provider | `@ai-sdk/openai` | 1.x |
 | Validation | `zod` | 3.x |
 | YAML Parser | `js-yaml` | 4.x |
 
@@ -244,6 +275,10 @@ Detailed documentation is available in [`docs/`](./docs/):
 - [Core Workflows](./docs/architecture/core-workflows.md)
 - [High-Level Architecture](./docs/architecture/high-level-architecture.md)
 
+## Newsletter
+
+[![Subscribe on Substack](https://img.shields.io/badge/Subscribe-Substack-orange?style=for-the-badge&logo=substack)](https://beddelprotocol.substack.com/subscribe)
+
 ## License
 
 [MIT](LICENSE)

package/dist/agents/assistant-bedrock.yaml

@@ -0,0 +1,19 @@
+# Built-in Bedrock Assistant
+# Uses Meta Llama 3.2 1B - lightweight and cheap model on Bedrock
+
+metadata:
+  name: "Bedrock Assistant"
+  version: "1.0.0"
+  description: "Simple assistant using Llama 3.2 1B (lightweight)"
+  builtin: true
+
+workflow:
+  - id: "chat"
+    type: "chat"
+    config:
+      provider: "bedrock"
+      model: "us.meta.llama3-2-1b-instruct-v1:0"
+      system: |
+        You are a helpful, friendly assistant. Be concise and direct.
+        Answer in the same language the user writes to you.
+      messages: "$input.messages"

package/dist/agents/assistant-openrouter.yaml

@@ -0,0 +1,16 @@
+# Built-in OpenRouter Assistant
+# Uses OpenRouter for access to 400+ models
+
+metadata:
+  name: "OpenRouter Assistant"
+  version: "1.0.0"
+  builtin: true
+
+workflow:
+  - id: "chat-interaction"
+    type: "chat"
+    config:
+      provider: "openrouter"
+      model: "qwen/qwen3-coder:free"
+      system: "You are a helpful assistant."
+      messages: "$input.messages"

package/dist/agents/assistant.yaml

@@ -0,0 +1,16 @@
+# Built-in Streaming Assistant
+# Uses Google Gemini for fast, streaming responses
+
+metadata:
+  name: "Streaming Assistant"
+  version: "1.0.0"
+  builtin: true
+
+workflow:
+  - id: "chat-interaction"
+    type: "chat"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: "You are a helpful assistant."
+      messages: "$input.messages"

package/dist/agents/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in Agents Registry
+ *
+ * Lists all agents bundled with the beddel package.
+ * These are available automatically without user configuration.
+ */
+/**
+ * List of built-in agent IDs available in the package
+ */
+export declare const BUILTIN_AGENTS: readonly ["assistant", "assistant-bedrock", "assistant-openrouter", "text-generator", "multi-step-assistant"];
+export type BuiltinAgentId = typeof BUILTIN_AGENTS[number];
+/**
+ * Get the absolute path to the built-in agents directory
+ */
+export declare function getBuiltinAgentsPath(): string;
+/**
+ * Check if an agent ID is a built-in agent
+ */
+export declare function isBuiltinAgent(agentId: string): agentId is BuiltinAgentId;
+/**
+ * Get the full path to a built-in agent YAML file
+ */
+export declare function getBuiltinAgentPath(agentId: BuiltinAgentId): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,eAAO,MAAM,cAAc,+GAMjB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAE3D;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,cAAc,CAEzE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEnE"}

package/dist/agents/index.js

@@ -0,0 +1,39 @@
+/**
+ * Built-in Agents Registry
+ *
+ * Lists all agents bundled with the beddel package.
+ * These are available automatically without user configuration.
+ */
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+// Get the directory where built-in agents are located
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * List of built-in agent IDs available in the package
+ */
+export const BUILTIN_AGENTS = [
+    'assistant',
+    'assistant-bedrock',
+    'assistant-openrouter',
+    'text-generator',
+    'multi-step-assistant',
+];
+/**
+ * Get the absolute path to the built-in agents directory
+ */
+export function getBuiltinAgentsPath() {
+    return __dirname;
+}
+/**
+ * Check if an agent ID is a built-in agent
+ */
+export function isBuiltinAgent(agentId) {
+    return BUILTIN_AGENTS.includes(agentId);
+}
+/**
+ * Get the full path to a built-in agent YAML file
+ */
+export function getBuiltinAgentPath(agentId) {
+    return join(__dirname, `${agentId}.yaml`);
+}

package/dist/agents/multi-step-assistant.yaml

@@ -0,0 +1,67 @@
+# Multi-Step Text Analyzer
+# Pipeline: Generate Text → Extract Entities → Classify Sentiment → Structured Summary
+
+metadata:
+  name: "Multi-Step Text Analyzer"
+  version: "1.0.0"
+  builtin: true
+  description: "4-step pipeline demonstrating variable passing between steps"
+
+workflow:
+  # Step 1: Generate sample text using text-generator agent
+  # Input: { messages: [{ role: "user", content: "Generate 200 chars about space exploration" }] }
+  - id: "generate-text"
+    type: "call-agent"
+    config:
+      agentId: "text-generator"
+      input:
+        messages: "$input.messages"
+    result: "generatedText"
+
+  # Step 2: Extract entities and topics from the generated text
+  - id: "extract-entities"
+    type: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: |
+        You are an entity extraction specialist. Analyze the given text and extract:
+        - Named entities (people, places, organizations, dates)
+        - Main topics/themes
+        - Key concepts
+        
+        Output ONLY valid JSON (no markdown, no explanation):
+        {"entities":{"people":[],"places":[],"organizations":[],"dates":[]},"topics":[],"concepts":[]}
+      messages:
+        - role: "user"
+          content: "$stepResult.generatedText.generatedText.text"
+    result: "entities"
+
+  # Step 3: Classify sentiment of the text
+  - id: "classify-sentiment"
+    type: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: |
+        You are a sentiment analysis expert. Analyze the emotional tone of the text.
+        
+        Output ONLY valid JSON (no markdown, no explanation):
+        {"overall":"positive|negative|neutral|mixed","confidence":0.8,"emotions":["joy"],"tone":"formal"}
+      messages:
+        - role: "user"
+          content: "$stepResult.generatedText.generatedText.text"
+    result: "sentiment"
+
+  # Step 4: Generate structured summary combining all analysis
+  - id: "final-summary"
+    type: "output-generator"
+    config:
+      template:
+        originalText: "$stepResult.generatedText.generatedText.text"
+        entities: "$stepResult.entities.text"
+        sentiment: "$stepResult.sentiment.text"
+        pipeline:
+          steps: 4
+          status: "completed"
+    result: "finalReport"

package/dist/agents/text-generator.yaml

@@ -0,0 +1,27 @@
+# Text Generator Agent
+# Generates text based on length and subject parameters
+# Uses lightweight model for efficiency
+
+metadata:
+  name: "Text Generator"
+  version: "1.0.0"
+  builtin: true
+  description: "Generates text with specified length and subject"
+
+workflow:
+  - id: "generate-text"
+    type: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: |
+        You are a text generator. Generate creative, coherent text based on the given parameters.
+        
+        RULES:
+        - Generate approximately the requested number of characters (can vary ±20%)
+        - Stay focused on the given subject/theme
+        - Write in a natural, engaging style
+        - Output ONLY the generated text, no explanations or meta-commentary
+        - Do not use markdown formatting unless specifically requested
+      messages: "$input.messages"
+    result: "generatedText"

package/dist/index.d.ts

@@ -16,5 +16,7 @@ export { toolRegistry, registerTool } from './tools';
 export type { ToolImplementation } from './tools';
 export { providerRegistry, registerProvider, createModel } from './providers';
 export type { ProviderImplementation, ProviderConfig } from './providers';
+export { BUILTIN_AGENTS, getBuiltinAgentsPath, getBuiltinAgentPath, isBuiltinAgent } from './agents';
+export type { BuiltinAgentId } from './agents';
 export type { ParsedYaml, WorkflowStep, StepConfig, YamlMetadata, ExecutionContext, PrimitiveHandler, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAIvD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG1E,YAAY,EACR,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAIvD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG1E,OAAO,EACH,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG/C,YAAY,EACR,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -18,3 +18,5 @@ export { handlerRegistry, registerPrimitive } from './primitives';
 export { toolRegistry, registerTool } from './tools';
 // Providers registry (for custom LLM provider registration)
 export { providerRegistry, registerProvider, createModel } from './providers';
+// Built-in agents registry
+export { BUILTIN_AGENTS, getBuiltinAgentsPath, getBuiltinAgentPath, isBuiltinAgent } from './agents';

package/dist/primitives/call-agent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Beddel Protocol - Call Agent Primitive
+ *
+ * Enables recursive workflow execution by calling other agents.
+ * This primitive loads and executes another agent's workflow,
+ * passing input and returning the result.
+ *
+ * Server-only: Uses loadYaml and WorkflowExecutor.
+ */
+import type { PrimitiveHandler } from '../types';
+/**
+ * Call Agent Primitive Handler
+ *
+ * Loads another agent's YAML and executes its workflow.
+ *
+ * IMPORTANT: If the called agent returns a Response (streaming),
+ * this primitive will return that Response, causing the parent
+ * workflow to also return immediately.
+ *
+ * For multi-step workflows, ensure called agents use stream: false
+ * so their results can be captured and passed to subsequent steps.
+ *
+ * @param config - Step configuration (agentId, input)
+ * @param context - Execution context with input and variables
+ * @returns Result from called agent (Response or Record)
+ */
+export declare const callAgentPrimitive: PrimitiveHandler;
+//# sourceMappingURL=call-agent.d.ts.map

package/dist/primitives/call-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-agent.d.ts","sourceRoot":"","sources":["../../src/primitives/call-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAwD/E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,EAAE,gBAyBhC,CAAC"}

package/dist/primitives/call-agent.js

@@ -0,0 +1,79 @@
+/**
+ * Beddel Protocol - Call Agent Primitive
+ *
+ * Enables recursive workflow execution by calling other agents.
+ * This primitive loads and executes another agent's workflow,
+ * passing input and returning the result.
+ *
+ * Server-only: Uses loadYaml and WorkflowExecutor.
+ */
+import { loadYaml } from '../core/parser';
+import { WorkflowExecutor } from '../core/workflow';
+import { resolveVariables } from '../core/variable-resolver';
+import { join } from 'path';
+import { access } from 'fs/promises';
+import { getBuiltinAgentsPath } from '../agents';
+/**
+ * Check if a file exists at the given path
+ */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve agent path with fallback chain:
+ * 1. User agents (agentsPath) - allows override
+ * 2. Built-in agents (package) - fallback
+ */
+async function resolveAgentPath(agentId, agentsPath) {
+    // 1. First: try user agents
+    const userPath = join(process.cwd(), agentsPath, `${agentId}.yaml`);
+    if (await fileExists(userPath)) {
+        return userPath;
+    }
+    // 2. Fallback: built-in agents from package
+    const builtinPath = join(getBuiltinAgentsPath(), `${agentId}.yaml`);
+    if (await fileExists(builtinPath)) {
+        return builtinPath;
+    }
+    throw new Error(`[Beddel] Agent not found: ${agentId}`);
+}
+/**
+ * Call Agent Primitive Handler
+ *
+ * Loads another agent's YAML and executes its workflow.
+ *
+ * IMPORTANT: If the called agent returns a Response (streaming),
+ * this primitive will return that Response, causing the parent
+ * workflow to also return immediately.
+ *
+ * For multi-step workflows, ensure called agents use stream: false
+ * so their results can be captured and passed to subsequent steps.
+ *
+ * @param config - Step configuration (agentId, input)
+ * @param context - Execution context with input and variables
+ * @returns Result from called agent (Response or Record)
+ */
+export const callAgentPrimitive = async (config, context) => {
+    const callConfig = config;
+    if (!callConfig.agentId) {
+        throw new Error('[Beddel] call-agent requires agentId in config');
+    }
+    // Resolve the input to pass to the agent
+    const agentInput = callConfig.input
+        ? resolveVariables(callConfig.input, context)
+        : context.input;
+    // Resolve agent path
+    const agentsPath = callConfig.agentsPath || 'src/agents';
+    const agentPath = await resolveAgentPath(callConfig.agentId, agentsPath);
+    // Load and execute the agent
+    const yaml = await loadYaml(agentPath);
+    const executor = new WorkflowExecutor(yaml);
+    const result = await executor.execute(agentInput);
+    return result;
+};

package/dist/primitives/chat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Beddel Protocol - Chat Primitive
+ *
+ * Primitive for frontend chat interfaces using useChat hook.
+ * ALWAYS streams responses for responsive UX.
+ * Expects UIMessage format (with 'parts' array) and converts to ModelMessage.
+ *
+ * Use this primitive when:
+ * - Input comes from useChat frontend hook
+ * - You need streaming responses to the client
+ *
+ * Server-only: Uses Vercel AI SDK Core.
+ */
+import type { PrimitiveHandler } from '../types';
+/**
+ * Chat Primitive Handler
+ *
+ * Converts UIMessage[] (from useChat) to ModelMessage[] and streams response.
+ * Always uses streaming mode for responsive frontend UX.
+ *
+ * @param config - Step configuration from YAML
+ * @param context - Execution context with input and variables
+ * @returns Response (always streaming)
+ */
+export declare const chatPrimitive: PrimitiveHandler;
+//# sourceMappingURL=chat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/primitives/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAK/E;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,gBA2C3B,CAAC"}

package/dist/primitives/chat.js

@@ -0,0 +1,63 @@
+/**
+ * Beddel Protocol - Chat Primitive
+ *
+ * Primitive for frontend chat interfaces using useChat hook.
+ * ALWAYS streams responses for responsive UX.
+ * Expects UIMessage format (with 'parts' array) and converts to ModelMessage.
+ *
+ * Use this primitive when:
+ * - Input comes from useChat frontend hook
+ * - You need streaming responses to the client
+ *
+ * Server-only: Uses Vercel AI SDK Core.
+ */
+import { streamText, convertToModelMessages, stepCountIs, } from 'ai';
+import { resolveVariables } from '../core/variable-resolver';
+import { createModel } from '../providers';
+import { mapTools, callbackRegistry } from './llm-core';
+/**
+ * Chat Primitive Handler
+ *
+ * Converts UIMessage[] (from useChat) to ModelMessage[] and streams response.
+ * Always uses streaming mode for responsive frontend UX.
+ *
+ * @param config - Step configuration from YAML
+ * @param context - Execution context with input and variables
+ * @returns Response (always streaming)
+ */
+export const chatPrimitive = async (config, context) => {
+    const llmConfig = config;
+    const model = createModel(llmConfig.provider || 'google', {
+        model: llmConfig.model || 'gemini-1.5-flash',
+    });
+    // Resolve and convert UIMessage to ModelMessage
+    const uiMessages = resolveVariables(llmConfig.messages, context);
+    const messages = await convertToModelMessages(uiMessages);
+    const hasTools = llmConfig.tools && llmConfig.tools.length > 0;
+    const tools = hasTools ? mapTools(llmConfig.tools) : undefined;
+    const result = streamText({
+        model,
+        messages,
+        system: llmConfig.system,
+        stopWhen: hasTools ? stepCountIs(5) : undefined,
+        tools,
+        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 result.toUIMessageStreamResponse();
+};

package/dist/primitives/index.d.ts

@@ -3,35 +3,29 @@
  *
  * 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 type { PrimitiveHandler } from '../types';
-export { llmPrimitive, registerCallback, callbackRegistry } from './llm';
+export { registerCallback, callbackRegistry } from './llm-core';
+export { chatPrimitive } from './chat';
+export { llmPrimitive } from './llm';
+export { callAgentPrimitive } from './call-agent';
 /**
  * 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)
+ * Primitives:
+ * - 'chat': Frontend chat interface (UIMessage with 'parts' → converts to ModelMessage)
+ * - 'llm': Workflow/API calls (ModelMessage with 'content' → direct use)
+ * - 'output-generator': Deterministic variable mapping
+ * - 'call-agent': Sub-agent invocation
  */
 export declare const handlerRegistry: Record<string, PrimitiveHandler>;
 /**
  * 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 declare function registerPrimitive(type: string, handler: PrimitiveHandler): void;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/primitives/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,UAAU,CAAC;AAK/E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAmBzE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAkB5D,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAK/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/primitives/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,UAAU,CAAC;AAO/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA0B5D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAK/E"}