beddel 1.0.1 → 1.0.3

package/README.md

@@ -14,6 +14,7 @@
 - 🔌 **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, Amazon Bedrock, and OpenRouter (400+ models)
 
 ## Installation
 
@@ -40,6 +41,8 @@ export const POST = createBeddelHandler({
 
 ### 2. Create YAML Agent
 
+#### Example 1: Google Gemini (Default Provider)
+
 ```yaml
 # src/agents/assistant.yaml
 metadata:
@@ -50,16 +53,47 @@ workflow:
   - id: "chat-interaction"
     type: "llm"
     config:
+      provider: "google"
       model: "gemini-2.0-flash-exp"
       stream: true
       system: "You are a helpful assistant."
       messages: "$input.messages"
 ```
 
-### 3. Set Environment Variable
+#### Example 2: Amazon Bedrock (Llama 3.2)
+
+```yaml
+# src/agents/assistant-bedrock.yaml
+metadata:
+  name: "Bedrock Assistant"
+  version: "1.0.0"
+  description: "Simple assistant using Llama 3.2 1B (lightweight)"
+
+workflow:
+  - id: "chat"
+    type: "llm"
+    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"
+```
+
+### 3. Set Environment Variables
 
 ```bash
+# For Google Gemini
 GEMINI_API_KEY=your_api_key_here
+
+# For Amazon Bedrock
+AWS_REGION=us-east-1
+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
 ```
 
 ### 4. Use with React (useChat)
@@ -71,7 +105,7 @@ import { useChat } from '@ai-sdk/react';
 export default function Chat() {
   const { messages, input, handleInputChange, handleSubmit } = useChat({
     api: '/api/beddel/chat',
-    body: { agentId: 'assistant' },
+    body: { agentId: 'assistant' },  // or 'assistant-bedrock'
   });
 
   return (
@@ -88,6 +122,35 @@ export default function Chat() {
 }
 ```
 
+## Built-in Providers
+
+| Provider | Environment Variables | Default Model |
+|----------|----------------------|---------------|
+| `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).
+
+### Example: OpenRouter (400+ Models)
+
+```yaml
+# src/agents/assistant-openrouter.yaml
+metadata:
+  name: "OpenRouter Assistant"
+  version: "1.0.0"
+
+workflow:
+  - id: "chat"
+    type: "llm"
+    config:
+      provider: "openrouter"
+      model: "qwen/qwen3-14b:free"  # or any model from openrouter.ai/models
+      stream: true
+      system: "You are a helpful assistant."
+      messages: "$input.messages"
+```
+
 ## Entry Points
 
 | Import Path | Purpose | Environment |
@@ -188,6 +251,8 @@ Beddel is fully compatible with Vercel AI SDK v6:
 | Runtime | Node.js / Edge | 20+ |
 | 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 |
 
@@ -200,6 +265,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,20 @@
+# 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: "llm"
+    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"

package/dist/agents/assistant-openrouter.yaml

@@ -0,0 +1,17 @@
+# 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: "llm"
+    config:
+      provider: "openrouter"
+      model: "qwen/qwen3-coder:free"
+      stream: true
+      system: "You are a helpful assistant."
+      messages: "$input.messages"

package/dist/agents/assistant.yaml

@@ -0,0 +1,17 @@
+# 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: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      stream: true
+      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"];
+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,qEAIjB,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,37 @@
+/**
+ * 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',
+];
+/**
+ * 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/index.d.ts

@@ -14,5 +14,9 @@ export { createBeddelHandler } from './server/handler';
 export { handlerRegistry, registerPrimitive } from './primitives';
 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,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

@@ -16,3 +16,7 @@ export { createBeddelHandler } from './server/handler';
 export { handlerRegistry, registerPrimitive } from './primitives';
 // Tools registry (for custom tool registration)
 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/llm.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/primitives/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAK/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;AA2DD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,gBA2E1B,CAAC"}

package/dist/primitives/llm.js

@@ -16,9 +16,9 @@
  * - 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';
+import { createModel } from '../providers';
 /**
  * Registry for consumer-registered callbacks.
  * Populated by the application using Beddel.
@@ -87,11 +87,10 @@ function mapTools(toolDefinitions) {
  */
 export const llmPrimitive = async (config, context) => {
     const llmConfig = config;
-    // Initialize Google Generative AI provider
-    const google = createGoogleGenerativeAI({
-        apiKey: process.env.GEMINI_API_KEY,
+    // Create model from provider registry (defaults to 'google')
+    const model = createModel(llmConfig.provider || 'google', {
+        model: llmConfig.model || 'gemini-1.5-flash',
     });
-    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);

package/dist/providers/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Beddel Protocol - Provider Registry
+ *
+ * This registry maps provider names to their implementations.
+ * Following Expansion Pack Pattern from BMAD-METHOD™ for extensibility.
+ * See: https://github.com/bmadcode/bmad-method
+ *
+ * Server-only: Providers may use Node.js APIs and external services.
+ */
+import type { LanguageModel } from 'ai';
+/**
+ * Configuration passed to provider's createModel method.
+ */
+export interface ProviderConfig {
+    model: string;
+    [key: string]: unknown;
+}
+/**
+ * Provider implementation interface.
+ * Each provider must implement createModel to return an AI SDK LanguageModel.
+ */
+export interface ProviderImplementation {
+    createModel: (config: ProviderConfig) => LanguageModel;
+}
+/**
+ * Registry of provider implementations keyed by provider name.
+ *
+ * Built-in Providers:
+ * - 'google': Google Gemini via @ai-sdk/google
+ * - 'bedrock': Amazon Bedrock via @ai-sdk/amazon-bedrock
+ */
+export declare const providerRegistry: Record<string, ProviderImplementation>;
+/**
+ * Register a custom provider implementation in the registry.
+ * Allows consumers to extend Beddel with additional LLM providers.
+ *
+ * @param name - Provider identifier (e.g., 'openai', 'anthropic')
+ * @param implementation - ProviderImplementation with createModel method
+ *
+ * @example
+ * import { registerProvider } from 'beddel';
+ *
+ * registerProvider('openai', {
+ *   createModel: (config) => {
+ *     const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ *     return openai(config.model || 'gpt-4');
+ *   },
+ * });
+ */
+export declare function registerProvider(name: string, implementation: ProviderImplementation): void;
+/**
+ * Create a LanguageModel instance from a registered provider.
+ *
+ * @param provider - Provider name (must be registered in providerRegistry)
+ * @param config - Configuration including model name and provider-specific options
+ * @returns LanguageModel instance from the AI SDK
+ * @throws Error if provider is not found, listing available providers
+ *
+ * @example
+ * const model = createModel('google', { model: 'gemini-1.5-flash' });
+ */
+export declare function createModel(provider: string, config: ProviderConfig): LanguageModel;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAKxC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,WAAW,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,aAAa,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAM,CAAC;AAE3E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,sBAAsB,GACvC,IAAI,CAKN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa,CAOnF"}

package/dist/providers/index.js

@@ -0,0 +1,115 @@
+/**
+ * Beddel Protocol - Provider Registry
+ *
+ * This registry maps provider names to their implementations.
+ * Following Expansion Pack Pattern from BMAD-METHOD™ for extensibility.
+ * See: https://github.com/bmadcode/bmad-method
+ *
+ * Server-only: Providers may use Node.js APIs and external services.
+ */
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+/**
+ * Registry of provider implementations keyed by provider name.
+ *
+ * Built-in Providers:
+ * - 'google': Google Gemini via @ai-sdk/google
+ * - 'bedrock': Amazon Bedrock via @ai-sdk/amazon-bedrock
+ */
+export const providerRegistry = {};
+/**
+ * Register a custom provider implementation in the registry.
+ * Allows consumers to extend Beddel with additional LLM providers.
+ *
+ * @param name - Provider identifier (e.g., 'openai', 'anthropic')
+ * @param implementation - ProviderImplementation with createModel method
+ *
+ * @example
+ * import { registerProvider } from 'beddel';
+ *
+ * registerProvider('openai', {
+ *   createModel: (config) => {
+ *     const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ *     return openai(config.model || 'gpt-4');
+ *   },
+ * });
+ */
+export function registerProvider(name, implementation) {
+    if (providerRegistry[name]) {
+        console.warn(`[Beddel] Provider '${name}' already registered, overwriting.`);
+    }
+    providerRegistry[name] = implementation;
+}
+/**
+ * Create a LanguageModel instance from a registered provider.
+ *
+ * @param provider - Provider name (must be registered in providerRegistry)
+ * @param config - Configuration including model name and provider-specific options
+ * @returns LanguageModel instance from the AI SDK
+ * @throws Error if provider is not found, listing available providers
+ *
+ * @example
+ * const model = createModel('google', { model: 'gemini-1.5-flash' });
+ */
+export function createModel(provider, config) {
+    const impl = providerRegistry[provider];
+    if (!impl) {
+        const available = Object.keys(providerRegistry).join(', ') || 'none';
+        throw new Error(`Unknown provider: '${provider}'. Available: ${available}`);
+    }
+    return impl.createModel(config);
+}
+// =============================================================================
+// Built-in Providers
+// =============================================================================
+/**
+ * Google Gemini Provider (Built-in)
+ *
+ * Uses @ai-sdk/google with GEMINI_API_KEY environment variable.
+ * Default model: gemini-1.5-flash
+ *
+ * Requirements: 1.2, 4.1
+ */
+registerProvider('google', {
+    createModel: (config) => {
+        const google = createGoogleGenerativeAI({
+            apiKey: process.env.GEMINI_API_KEY,
+        });
+        return google(config.model || 'gemini-1.5-flash');
+    },
+});
+/**
+ * Amazon Bedrock Provider (Built-in)
+ *
+ * Uses @ai-sdk/amazon-bedrock with AWS_BEARER_TOKEN_BEDROCK environment variable.
+ * Region is configured via AWS_REGION env var or defaults to 'us-east-1'.
+ * Default model: anthropic.claude-3-haiku-20240307-v1:0
+ *
+ * Requirements: 1.3, 4.2
+ */
+registerProvider('bedrock', {
+    createModel: (config) => {
+        const bedrock = createAmazonBedrock({
+            region: process.env.AWS_REGION || 'us-east-1',
+        });
+        return bedrock(config.model || 'anthropic.claude-3-haiku-20240307-v1:0');
+    },
+});
+/**
+ * OpenRouter Provider (Built-in)
+ *
+ * Uses @openrouter/ai-sdk-provider for access to 400+ models.
+ * Requires OPENROUTER_API_KEY environment variable.
+ * Default model: qwen/qwen3-coder:free (free tier)
+ *
+ * Requirements: 1.4, 4.3
+ */
+registerProvider('openrouter', {
+    createModel: (config) => {
+        const openrouter = createOpenRouter({
+            apiKey: process.env.OPENROUTER_API_KEY,
+        });
+        return openrouter(config.model || 'qwen/qwen3-coder:free');
+    },
+});

package/dist/server/handler.d.ts

@@ -1,6 +1,9 @@
 import { NextRequest } from 'next/server';
 export interface BeddelHandlerOptions {
+    /** Path to user-defined agents (relative to CWD). Default: 'src/agents' */
     agentsPath?: string;
+    /** Disable built-in agents bundled with the package. Default: false */
+    disableBuiltinAgents?: boolean;
 }
 export type BeddelHandler = (request: NextRequest) => Promise<Response>;
 export declare function createBeddelHandler(options?: BeddelHandlerOptions): BeddelHandler;

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

@@ -1 +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"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/server/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO1C,MAAM,WAAW,oBAAoB;IACjC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAwDxE,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CA0CrF"}

package/dist/server/handler.js

@@ -1,25 +1,56 @@
 import { loadYaml } from '../core/parser';
 import { WorkflowExecutor } from '../core/workflow';
 import { join, normalize } from 'path';
+import { access } from 'fs/promises';
+import { getBuiltinAgentsPath } from '../agents';
 /**
  * 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);
 }
+/**
+ * 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, userAgentsPath, disableBuiltinAgents) {
+    // 1. First: try user agents (allows override of built-in)
+    const basePath = join(process.cwd(), userAgentsPath);
+    const userPath = normalize(join(basePath, `${agentId}.yaml`));
+    // Security: ensure resolved path is within user agents directory
+    if (userPath.startsWith(basePath) && await fileExists(userPath)) {
+        return userPath;
+    }
+    // 2. Fallback: built-in agents from package
+    if (!disableBuiltinAgents) {
+        const builtinPath = join(getBuiltinAgentsPath(), `${agentId}.yaml`);
+        if (await fileExists(builtinPath)) {
+            return builtinPath;
+        }
+    }
+    throw new Error(`Agent not found: ${agentId}`);
+}
 export function createBeddelHandler(options = {}) {
     const agentsPath = options.agentsPath || 'src/agents';
+    const disableBuiltinAgents = options.disableBuiltinAgents || false;
     return async function POST(request) {
         try {
             const body = await request.json();
@@ -31,16 +62,10 @@ export function createBeddelHandler(options = {}) {
             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 });
-            }
+            // Resolve agent path with fallback chain
+            const fullPath = await resolveAgentPath(agentId, agentsPath, disableBuiltinAgents);
             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;

package/dist/validation/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Beddel Protocol - Validation Module
+ * Schema validation using Zod with stream/output constraint enforcement
+ */
+import { ZodSchema } from 'zod';
+import type { SchemaSpec, ParsedYaml } from '../types';
+/**
+ * Validation error with detailed issue list
+ */
+export declare class ValidationError extends Error {
+    details: string[];
+    constructor(message: string, details: string[]);
+}
+/**
+ * Convert SchemaSpec to Zod schema
+ */
+export declare function schemaSpecToZod(spec: SchemaSpec): ZodSchema;
+/**
+ * Validate data against SchemaSpec
+ */
+export declare function validateSchema(spec: SchemaSpec, data: unknown): {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: ValidationError;
+};
+/**
+ * Validate YAML structure for stream/output constraint
+ * @throws ValidationError if stream: true AND output schema is defined
+ */
+export declare function validateYamlConstraints(yaml: ParsedYaml): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEvD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACF,OAAO,EAAE,MAAM,EAAE;gBAAzC,OAAO,EAAE,MAAM,EAAS,OAAO,EAAE,MAAM,EAAE;CAIxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAqB3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC1B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,OAAO,GACd;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAa/E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAiB9D"}