beddel 1.0.6 → 1.0.7

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.4-brightgreen.svg)](https://www.npmjs.com/package/beddel)
+[![npm version](https://img.shields.io/badge/npm-1.0.7-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/)
 
@@ -236,6 +236,7 @@ workflow:
 |---------|-------------|---------|
 | `$input.*` | Access request input | `$input.messages` |
 | `$stepResult.varName.*` | Access step result | `$stepResult.llmOutput.text` |
+| `$env.*` | Access environment variables | `$env.NOTION_DATABASE_ID` |
 
 ## Built-in Tools
 

package/dist/agents/{business-analyzer.yaml → google-business/business-analyzer.yaml}

@@ -13,8 +13,9 @@
 
 metadata:
   name: "Business Analyzer"
-  version: "1.0.0"
+  version: "1.1.0"
   description: "Analyzes business reviews and generates actionable insights"
+  builtin: true
 
 workflow:
   # Step 1: Fetch all reviews with auto-pagination
@@ -46,20 +47,28 @@ workflow:
         5. Trend analysis comparing recent vs older reviews
         6. Actionable recommendations
         
-        Format your response as structured JSON.
+        Return ONLY valid JSON (no markdown, no ```):
+        {
+          "sentimentScore": 8,
+          "positiveThemes": [{"theme": "Great service", "count": 15}],
+          "improvementAreas": [{"area": "Wait times", "count": 5}],
+          "urgentReviews": [{"reviewId": "xxx", "rating": 1, "issue": "summary"}],
+          "trendAnalysis": "Recent reviews show improvement...",
+          "recommendations": ["Focus on...", "Consider..."]
+        }
       messages:
         - role: "user"
-          content: |
-            Analyze these business reviews:
-            
-            Total Reviews: $stepResult.reviewsData.totalReviewCount
-            Average Rating: $stepResult.reviewsData.averageRating
-            
-            Reviews Data:
-            $stepResult.reviewsData.reviews
+          content: "$input.reviewsPayload"
+    result: "analysisRaw"
+
+  # Step 3: Parse analysis JSON
+  - id: "parse-analysis"
+    type: "output-generator"
+    config:
+      json: "$stepResult.analysisRaw.text"
     result: "analysis"
 
-  # Step 3: Generate response suggestions for negative reviews
+  # Step 4: Generate response suggestions for negative reviews
   - id: "generate-responses"
     type: "llm"
     config:
@@ -76,24 +85,29 @@ workflow:
         - Keep responses under 150 words
         - Be specific to the complaint mentioned
         
-        Format as JSON array with reviewId and suggestedResponse.
+        Return ONLY valid JSON array (no markdown, no ```):
+        [{"reviewId": "xxx", "rating": 2, "originalComment": "...", "suggestedResponse": "..."}]
+        
+        If no negative reviews, return: []
       messages:
         - role: "user"
-          content: |
-            Generate response suggestions for these reviews:
-            $stepResult.reviewsData.reviews
-    result: "responseSuggestions"
+          content: "$input.reviewsPayload"
+    result: "responsesRaw"
 
-  # Step 4: Compile final report
-  - id: "compile-report"
+  # Step 5: Parse responses JSON
+  - id: "parse-responses"
     type: "output-generator"
     config:
-      template:
-        summary:
-          totalReviews: "$stepResult.reviewsData.totalReviewCount"
-          averageRating: "$stepResult.reviewsData.averageRating"
-          analysisDate: "$input.analysisDate"
-        analysis: "$stepResult.analysis.text"
-        responseSuggestions: "$stepResult.responseSuggestions.text"
-        rawReviews: "$stepResult.reviewsData.reviews"
-    result: "finalReport"
+      json: "$stepResult.responsesRaw.text"
+    result: "responseSuggestions"
+
+# Explicit Return: Define the API response contract
+return:
+  success: true
+  summary:
+    totalReviews: "$stepResult.reviewsData.totalReviewCount"
+    averageRating: "$stepResult.reviewsData.averageRating"
+    pagesFetched: "$stepResult.reviewsData.data.pagesFetched"
+  analysis: "$stepResult.analysis"
+  responseSuggestions: "$stepResult.responseSuggestions"
+  reviews: "$stepResult.reviewsData.reviews"

package/dist/agents/index.d.ts

@@ -3,12 +3,24 @@
  *
  * Lists all agents bundled with the beddel package.
  * These are available automatically without user configuration.
+ *
+ * Agents are organized by category:
+ * - chat/         Streaming chat assistants (different providers)
+ * - mcp/          MCP server integrations (GitMCP, Context7, etc.)
+ * - google-business/  Google Business Profile agents
+ * - marketing/    Lead capture, newsletters, CRM
+ * - utility/      General-purpose tools
+ * - examples/     Demo pipelines showing multi-step workflows
+ */
+/**
+ * Built-in agent definitions with their category paths
  */
+export declare const BUILTIN_AGENT_PATHS: Record<string, string>;
 /**
  * List of built-in agent IDs available in the package
  */
-export declare const BUILTIN_AGENTS: readonly ["assistant", "assistant-bedrock", "assistant-openrouter", "assistant-gitmcp", "text-generator", "multi-step-assistant", "business-analyzer"];
-export type BuiltinAgentId = typeof BUILTIN_AGENTS[number];
+export declare const BUILTIN_AGENTS: readonly string[];
+export type BuiltinAgentId = keyof typeof BUILTIN_AGENT_PATHS;
 /**
  * Get the absolute path to the built-in agents directory
  */
@@ -20,5 +32,14 @@ export declare function isBuiltinAgent(agentId: string): agentId is BuiltinAgent
 /**
  * Get the full path to a built-in agent YAML file
  */
-export declare function getBuiltinAgentPath(agentId: BuiltinAgentId): string;
+export declare function getBuiltinAgentPath(agentId: string): string | null;
+/**
+ * Get all agents in a specific category
+ */
+export declare function getAgentsByCategory(category: string): string[];
+/**
+ * Available categories
+ */
+export declare const AGENT_CATEGORIES: readonly ["chat", "mcp", "google-business", "marketing", "utility", "examples"];
+export type AgentCategory = typeof AGENT_CATEGORIES[number];
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,eAAO,MAAM,cAAc,wJAQjB,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBtD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAuC,SAAS,MAAM,EAAE,CAAC;AAEpF,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE9D;;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,MAAM,GAAG,MAAM,GAAG,IAAI,CAIlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAI9D;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,iFAOnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC"}

package/dist/agents/index.js

@@ -3,24 +3,43 @@
  *
  * Lists all agents bundled with the beddel package.
  * These are available automatically without user configuration.
+ *
+ * Agents are organized by category:
+ * - chat/         Streaming chat assistants (different providers)
+ * - mcp/          MCP server integrations (GitMCP, Context7, etc.)
+ * - google-business/  Google Business Profile agents
+ * - marketing/    Lead capture, newsletters, CRM
+ * - utility/      General-purpose tools
+ * - examples/     Demo pipelines showing multi-step workflows
  */
 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);
+/**
+ * Built-in agent definitions with their category paths
+ */
+export const BUILTIN_AGENT_PATHS = {
+    // Chat assistants
+    'assistant': 'chat/assistant.yaml',
+    'assistant-bedrock': 'chat/assistant-bedrock.yaml',
+    'assistant-openrouter': 'chat/assistant-openrouter.yaml',
+    // MCP integrations
+    'assistant-gitmcp': 'mcp/assistant-gitmcp.yaml',
+    // Google Business
+    'business-analyzer': 'google-business/business-analyzer.yaml',
+    // Marketing
+    'newsletter-signup': 'marketing/newsletter-signup.yaml',
+    // Utility
+    'text-generator': 'utility/text-generator.yaml',
+    // Examples
+    'multi-step-assistant': 'examples/multi-step-assistant.yaml',
+};
 /**
  * List of built-in agent IDs available in the package
  */
-export const BUILTIN_AGENTS = [
-    'assistant',
-    'assistant-bedrock',
-    'assistant-openrouter',
-    'assistant-gitmcp',
-    'text-generator',
-    'multi-step-assistant',
-    'business-analyzer',
-];
+export const BUILTIN_AGENTS = Object.keys(BUILTIN_AGENT_PATHS);
 /**
  * Get the absolute path to the built-in agents directory
  */
@@ -31,11 +50,33 @@ export function getBuiltinAgentsPath() {
  * Check if an agent ID is a built-in agent
  */
 export function isBuiltinAgent(agentId) {
-    return BUILTIN_AGENTS.includes(agentId);
+    return agentId in BUILTIN_AGENT_PATHS;
 }
 /**
  * Get the full path to a built-in agent YAML file
  */
 export function getBuiltinAgentPath(agentId) {
-    return join(__dirname, `${agentId}.yaml`);
+    const relativePath = BUILTIN_AGENT_PATHS[agentId];
+    if (!relativePath)
+        return null;
+    return join(__dirname, relativePath);
+}
+/**
+ * Get all agents in a specific category
+ */
+export function getAgentsByCategory(category) {
+    return Object.entries(BUILTIN_AGENT_PATHS)
+        .filter(([_, path]) => path.startsWith(`${category}/`))
+        .map(([id]) => id);
 }
+/**
+ * Available categories
+ */
+export const AGENT_CATEGORIES = [
+    'chat',
+    'mcp',
+    'google-business',
+    'marketing',
+    'utility',
+    'examples',
+];

package/dist/agents/marketing/newsletter-signup.yaml

@@ -0,0 +1,106 @@
+# Newsletter Signup Agent
+# Registers users to the newsletter with AI analysis and saves to Notion
+#
+# Required Environment Variables:
+# - NOTION_TOKEN (Internal Integration Secret)
+# - NOTION_DATABASE_ID (Database ID for newsletter signups)
+# - GEMINI_API_KEY (for AI analysis)
+#
+# Input:
+# - name: User's name
+# - email: User's email
+# - message: Optional message from user
+# - createdAt: ISO date string
+
+metadata:
+  name: "Newsletter Signup Agent"
+  version: "1.3.0"
+  description: "Registers users to the newsletter with AI analysis and saves to Notion"
+  builtin: true
+
+workflow:
+  # Step 1: Analyze user profile and generate structured JSON
+  - id: "analyze-user"
+    type: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: |
+        You are a lead analyst for a technology newsletter.
+        
+        Analyze the user data and return ONLY a valid JSON (no markdown, no ```):
+        {
+          "tags": [{"name": "Tag1"}],
+          "sentiment": {"name": "Positive"},
+          "summary": "One-line summary"
+        }
+        
+        IMPORTANT RULES:
+        - tags: Array of objects with "name". Allowed values: "Support", "Sales", "Partnership", "Feedback"
+        - sentiment: Object with "name". Allowed values: "Positive", "Neutral", "Negative"
+        - summary: Short summary string (maximum 100 characters)
+        
+        Example for a positive message about the product:
+        {"tags": [{"name": "Feedback"}], "sentiment": {"name": "Positive"}, "summary": "User praises the product"}
+        
+        If there is no significant message:
+        {"tags": [{"name": "Feedback"}], "sentiment": {"name": "Neutral"}, "summary": "New newsletter subscriber"}
+        
+        Return ONLY the JSON, nothing else.
+      messages:
+        - role: "user"
+          content: |
+            Name: $input.name
+            Email: $input.email
+            Message: $input.message
+    result: "userAnalysis"
+
+  # Step 2: Parse the JSON from LLM
+  - id: "parse-analysis"
+    type: "output-generator"
+    config:
+      json: "$stepResult.userAnalysis.text"
+    result: "parsedAnalysis"
+
+  # Step 3: Create Notion page with structured data
+  - id: "create-notion-entry"
+    type: "notion"
+    config:
+      action: "createPage"
+      parent:
+        type: "database_id"
+        database_id: "$env.NOTION_DATABASE_ID"
+      properties:
+        Name:
+          title:
+            - text:
+                content: "$input.name"
+        Email:
+          email: "$input.email"
+        Message:
+          rich_text:
+            - text:
+                content: "$input.message"
+        Summary:
+          rich_text:
+            - text:
+                content: "$stepResult.parsedAnalysis.summary"
+        Tags:
+          multi_select: "$stepResult.parsedAnalysis.tags"
+        Sentiment:
+          select: "$stepResult.parsedAnalysis.sentiment"
+        CreatedAt:
+          date:
+            start: "$input.createdAt"
+    result: "notionResult"
+
+# Explicit Return: Define the API response contract
+return:
+  success: true
+  message: "Registration completed successfully!"
+  notionPageId: "$stepResult.notionResult.pageId"
+  notionUrl: "$stepResult.notionResult.url"
+  analysis:
+    tags: "$stepResult.parsedAnalysis.tags"
+    sentiment: "$stepResult.parsedAnalysis.sentiment"
+    summary: "$stepResult.parsedAnalysis.summary"

package/dist/server/handler.js

@@ -2,7 +2,7 @@ import { loadYaml } from '../core/parser';
 import { WorkflowExecutor } from '../core/workflow';
 import { join, normalize } from 'path';
 import { access } from 'fs/promises';
-import { getBuiltinAgentsPath } from '../agents';
+import { getBuiltinAgentPath } from '../agents';
 /**
  * Validate agentId to prevent path traversal attacks.
  * Only allows alphanumeric characters, hyphens, and underscores.
@@ -39,10 +39,10 @@ async function resolveAgentPath(agentId, userAgentsPath, disableBuiltinAgents) {
     if (userPath.startsWith(basePath) && await fileExists(userPath)) {
         return userPath;
     }
-    // 2. Fallback: built-in agents from package
+    // 2. Fallback: built-in agents from package (supports subfolder structure)
     if (!disableBuiltinAgents) {
-        const builtinPath = join(getBuiltinAgentsPath(), `${agentId}.yaml`);
-        if (await fileExists(builtinPath)) {
+        const builtinPath = getBuiltinAgentPath(agentId);
+        if (builtinPath && await fileExists(builtinPath)) {
             return builtinPath;
         }
     }

package/docs/architecture/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-> **Beddel Protocol v1.0.4** — Complete API documentation for all public exports.
+> **Beddel Protocol v1.0.6** — Complete API documentation for all public exports.
 
 ---
 
@@ -31,7 +31,7 @@ console.log(yaml.metadata.name); // "Streaming Assistant"
 
 #### `resolveVariables(template: unknown, context: ExecutionContext): unknown`
 
-Resolve variable references (`$input.*`, `$stepResult.*`) in templates.
+Resolve variable references (`$input.*`, `$stepResult.*`, `$env.*`) in templates.
 
 ```typescript
 import { resolveVariables } from 'beddel';
@@ -81,6 +81,8 @@ Map of primitive step types to their handler functions.
 - `output-generator` — Deterministic JSON transform
 - `call-agent` — Sub-agent invocation
 - `mcp-tool` — External MCP server tool execution
+- `google-business` — Google Business Profile API integration
+- `notion` — Notion workspace integration (pages, databases, blocks)
 
 #### `toolRegistry: Record<string, ToolImplementation>`
 
@@ -240,6 +242,59 @@ import type {
 
 ---
 
+## YAML Workflow Structure
+
+### Explicit Return Template
+
+The `return` property at the workflow level defines the exact shape of the API response. This provides explicit control over the API contract, separating internal workflow state from the public response.
+
+**Without `return`:** API returns all accumulated step variables (internal state exposed)
+
+**With `return`:** API returns only the resolved template (clean contract)
+
+```yaml
+metadata:
+  name: "Newsletter Signup"
+  version: "1.0.0"
+
+workflow:
+  - id: "analyze"
+    type: "llm"
+    config:
+      # ... LLM config ...
+    result: "analysis"  # Stored internally
+
+  - id: "save"
+    type: "notion"
+    config:
+      # ... Notion config ...
+    result: "notionResult"  # Stored internally
+
+# Explicit API response shape
+return:
+  success: true
+  pageId: "$stepResult.notionResult.pageId"
+  url: "$stepResult.notionResult.url"
+  summary: "$stepResult.analysis.text"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "pageId": "abc123...",
+  "url": "https://notion.so/...",
+  "summary": "Analysis text..."
+}
+```
+
+**Return Resolution Order:**
+1. If `return` is defined → resolve and return the template
+2. If last step has no `result` → return last step's output directly
+3. Otherwise → return all accumulated variables
+
+---
+
 ## Primitives
 
 ### `chat` Primitive
@@ -316,7 +371,16 @@ workflow:
 
 ### `output-generator` Primitive
 
-Deterministic JSON transform using variable resolution.
+Deterministic JSON transform using variable resolution. Supports optional JSON parsing from LLM text output.
+
+**Config Options:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `template` | `object` | No | JSON template with variable references |
+| `json` | `string` | No | Variable reference to parse as JSON (e.g., `$stepResult.llmOutput.text`) |
+
+**Basic Usage:**
 
 ```yaml
 workflow:
@@ -329,6 +393,36 @@ workflow:
     result: "finalOutput"
 ```
 
+**JSON Parsing from LLM Output:**
+
+When LLM returns JSON as text, use the `json` parameter to parse it and access fields via `$json.*`:
+
+```yaml
+workflow:
+  # Step 1: LLM generates JSON
+  - id: "analyze"
+    type: "llm"
+    config:
+      system: "Return JSON: {\"tags\": [\"tag1\"], \"sentiment\": \"Positive\"}"
+      messages: "$input.messages"
+    result: "analysis"
+
+  # Step 2: Parse JSON and extract fields
+  - id: "parse"
+    type: "output-generator"
+    config:
+      json: "$stepResult.analysis.text"
+      template:
+        tags: "$json.tags"
+        sentiment: "$json.sentiment"
+    result: "parsed"
+```
+
+The `json` parameter:
+- Extracts JSON from markdown code blocks if present
+- Parses the JSON and makes it available as `$json.*`
+- If no template is provided, returns the parsed JSON directly
+
 ### `mcp-tool` Primitive
 
 Connect to external MCP servers via SSE and execute tools.
@@ -389,18 +483,102 @@ workflow:
       messages: "$input.messages"
 ```
 
+### `notion` Primitive
+
+Integrate with Notion API for pages, databases, blocks, and search.
+
+**Environment Variables:**
+- `NOTION_TOKEN` — Internal Integration Secret (starts with `ntn_`)
+
+**Supported Actions:**
+
+| Action | Description | Required Config |
+|--------|-------------|-----------------|
+| `search` | Search pages and databases | `query?`, `filter?` |
+| `getPage` | Retrieve a page by ID | `pageId` |
+| `createPage` | Create a new page | `parent`, `properties` |
+| `updatePage` | Update page properties | `pageId`, `properties?` |
+| `getDatabase` | Retrieve database schema | `databaseId` |
+| `queryDatabase` | Query database with filters | `databaseId`, `filter?`, `sorts?` |
+| `getBlocks` | Get block children | `blockId` or `pageId` |
+| `appendBlocks` | Append blocks to page/block | `blockId` or `pageId`, `children` |
+| `createDatabase` | Create a new database | `parent`, `properties`, `title?` |
+
+**Example:**
+
+```yaml
+workflow:
+  - id: "create-entry"
+    type: "notion"
+    config:
+      action: "createPage"
+      parent:
+        type: "database_id"
+        database_id: "a7661a0a-c5b7-47a0-98f8-fd07789d1647"
+      properties:
+        Name:
+          title:
+            - text:
+                content: "$input.name"
+        Email:
+          email: "$input.email"
+    result: "notionResult"
+```
+
+> See `packages/beddel/docs/primitives/notion-primitive.md` for full documentation.
+
+### `google-business` Primitive
+
+Integrate with Google Business Profile APIs for reviews, posts, Q&A, and metrics.
+
+**Environment Variables:**
+- `GOOGLE_CLIENT_ID` — OAuth2 Client ID
+- `GOOGLE_CLIENT_SECRET` — OAuth2 Client Secret
+- `GOOGLE_REFRESH_TOKEN` — OAuth2 Refresh Token
+
+**Supported Actions:**
+
+| Action | Description |
+|--------|-------------|
+| `listReviews` | Fetch reviews with auto-pagination |
+| `replyReview` | Reply to a specific review |
+| `batchGetReviews` | Fetch from multiple locations |
+| `createPost` | Create a local post |
+| `listPosts` | List all posts |
+| `getMetrics` | Fetch performance metrics |
+| `listQuestions` | List Q&A |
+| `answerQuestion` | Answer a question |
+
+**Example:**
+
+```yaml
+workflow:
+  - id: "fetch-reviews"
+    type: "google-business"
+    config:
+      action: "listReviews"
+      accountId: "$input.accountId"
+      locationId: "$input.locationId"
+      pageSize: 100
+    result: "reviewsData"
+```
+
+> See `packages/beddel/docs/primitives/google-business-primitive.md` for full documentation.
+
 ---
 
 ## Built-in Agents
 
-| Agent ID | Provider | Description |
-|----------|----------|-------------|
-| `assistant` | Google | Streaming chat assistant |
-| `assistant-bedrock` | Bedrock | Llama 3.2 assistant |
-| `assistant-openrouter` | OpenRouter | Free tier assistant |
-| `assistant-gitmcp` | Google + MCP | Documentation assistant via GitMCP |
-| `text-generator` | Google | Text generation (non-streaming) |
-| `multi-step-assistant` | Google | 4-step analysis pipeline |
+| Agent ID | Category | Provider | Description |
+|----------|----------|----------|-------------|
+| `assistant` | `chat/` | Google | Streaming chat assistant |
+| `assistant-bedrock` | `chat/` | Bedrock | Llama 3.2 assistant |
+| `assistant-openrouter` | `chat/` | OpenRouter | Free tier assistant |
+| `assistant-gitmcp` | `mcp/` | Google + MCP | Documentation assistant via GitMCP |
+| `business-analyzer` | `google-business/` | Google | Business reviews analyzer |
+| `newsletter-signup` | `marketing/` | Google | Lead capture with Notion integration |
+| `text-generator` | `utility/` | Google | Text generation (non-streaming) |
+| `multi-step-assistant` | `examples/` | Google | 4-step analysis pipeline |
 
 ---
 
@@ -412,6 +590,7 @@ workflow:
 interface ParsedYaml {
   metadata: YamlMetadata;
   workflow: WorkflowStep[];
+  return?: unknown;  // Optional explicit return template
 }
 ```
 
@@ -456,3 +635,7 @@ type PrimitiveHandler = (
 | 2024-12-26 | 1.0.3 | OpenRouter provider, built-in agents |
 | 2024-12-27 | 1.0.4 | Separated `chat` and `llm` primitives, implemented `call-agent` |
 | 2024-12-28 | 1.0.5 | Added `mcp-tool` primitive, `assistant-gitmcp` agent, system prompt variable resolution |
+| 2024-12-30 | 1.0.6 | Added `google-business` primitive for Google Business Profile API |
+| 2026-01-01 | 1.0.7 | Added `notion` primitive for Notion API integration |
+| 2026-01-19 | 1.0.8 | Added `json` parameter to `output-generator`, explicit `return` template support |
+| 2026-01-19 | 1.0.9 | Reorganized built-in agents into category subfolders, added `newsletter-signup` agent |

package/docs/architecture/components.md

@@ -31,7 +31,7 @@
 
 ### Variable Resolver (`src/core/variable-resolver.ts`)
 
-**Responsibility:** Resolve `$input.*` and `$stepResult.*` variable references.
+**Responsibility:** Resolve `$input.*`, `$stepResult.*`, and `$env.*` variable references.
 
 **Key Interfaces:**
 - `resolveVariables(template: any, context: ExecutionContext): any`
@@ -249,16 +249,20 @@ This design is cleaner than a `stream: true/false` flag because:
 
 ## Built-in Agents (`src/agents/`)
 
-Pre-configured agents bundled with the package:
+Pre-configured agents bundled with the package, organized by category:
 
-| Agent | Type | Description |
-|-------|------|-------------|
-| `assistant.yaml` | `chat` | Google Gemini streaming assistant |
-| `assistant-bedrock.yaml` | `chat` | Amazon Bedrock assistant |
-| `assistant-openrouter.yaml` | `chat` | OpenRouter free tier assistant |
-| `assistant-gitmcp.yaml` | `mcp-tool` + `chat` | Documentation assistant via GitMCP |
-| `text-generator.yaml` | `llm` | Text generation (non-streaming) |
-| `multi-step-assistant.yaml` | `call-agent` + `llm` | 4-step analysis pipeline |
+| Agent | Category | Type | Description |
+|-------|----------|------|-------------|
+| `assistant` | `chat/` | `chat` | Google Gemini streaming assistant |
+| `assistant-bedrock` | `chat/` | `chat` | Amazon Bedrock assistant |
+| `assistant-openrouter` | `chat/` | `chat` | OpenRouter free tier assistant |
+| `assistant-gitmcp` | `mcp/` | `mcp-tool` + `chat` | Documentation assistant via GitMCP |
+| `business-analyzer` | `google-business/` | `google-business` + `llm` | Business reviews analyzer |
+| `newsletter-signup` | `marketing/` | `llm` + `notion` | Lead capture with Notion |
+| `text-generator` | `utility/` | `llm` | Text generation (non-streaming) |
+| `multi-step-assistant` | `examples/` | `call-agent` + `llm` | 4-step analysis pipeline |
+
+**Categories:** `chat/`, `mcp/`, `google-business/`, `marketing/`, `utility/`, `examples/`
 
 ---
 

package/docs/architecture/core-workflows.md

@@ -167,6 +167,7 @@ workflow:
 |---------|-------------|---------|
 | `$input.*` | Access request input data | `$input.messages` |
 | `$stepResult.varName.*` | Access step result by name | `$stepResult.llmOutput.text` |
+| `$env.*` | Access environment variables | `$env.NOTION_DATABASE_ID` |
 
 ---
 

package/docs/architecture/source-tree.md

@@ -7,13 +7,21 @@ packages/beddel/
 │   ├── server.ts                 # Server handler barrel export
 │   ├── client.ts                 # Client exports (types only, browser-safe)
 │   ├── agents/                   # Built-in agents (bundled with package)
-│   │   ├── index.ts              # Built-in agents registry
-│   │   ├── assistant.yaml        # Google Gemini streaming assistant
-│   │   ├── assistant-bedrock.yaml # Amazon Bedrock assistant
-│   │   ├── assistant-openrouter.yaml # OpenRouter assistant
-│   │   ├── text-generator.yaml   # Text generation (non-streaming)
-│   │   ├── multi-step-assistant.yaml # 4-step analysis pipeline
-│   │   └── assistant-gitmcp.yaml # GitMCP documentation assistant
+│   │   ├── index.ts              # Built-in agents registry (BUILTIN_AGENT_PATHS)
+│   │   ├── chat/                 # Streaming chat assistants
+│   │   │   ├── assistant.yaml
+│   │   │   ├── assistant-bedrock.yaml
+│   │   │   └── assistant-openrouter.yaml
+│   │   ├── mcp/                  # MCP server integrations
+│   │   │   └── assistant-gitmcp.yaml
+│   │   ├── google-business/      # Google Business Profile agents
+│   │   │   └── business-analyzer.yaml
+│   │   ├── marketing/            # Lead capture, newsletters
+│   │   │   └── newsletter-signup.yaml
+│   │   ├── utility/              # General-purpose tools
+│   │   │   └── text-generator.yaml
+│   │   └── examples/             # Demo pipelines
+│   │       └── multi-step-assistant.yaml
 │   ├── core/
 │   │   ├── parser.ts             # YAML parsing (FAILSAFE_SCHEMA)
 │   │   ├── workflow.ts           # WorkflowExecutor class
@@ -86,20 +94,33 @@ primitives/
 
 ## Built-in Agents
 
-Agents bundled with the package, available without configuration:
-
-| File | Type | Provider | Description |
-|------|------|----------|-------------|
-| `assistant.yaml` | `chat` | Google | Streaming chat assistant |
-| `assistant-bedrock.yaml` | `chat` | Bedrock | Llama 3.2 assistant |
-| `assistant-openrouter.yaml` | `chat` | OpenRouter | Free tier assistant |
-| `assistant-gitmcp.yaml` | `mcp-tool` + `chat` | Google + MCP | Documentation assistant via GitMCP |
-| `text-generator.yaml` | `llm` | Google | Text generation |
-| `multi-step-assistant.yaml` | `call-agent` + `llm` | Google | 4-step pipeline |
+Agents bundled with the package, available without configuration. Organized by category:
+
+| Agent ID | Category | Type | Provider | Description |
+|----------|----------|------|----------|-------------|
+| `assistant` | `chat/` | `chat` | Google | Streaming chat assistant |
+| `assistant-bedrock` | `chat/` | `chat` | Bedrock | Llama 3.2 assistant |
+| `assistant-openrouter` | `chat/` | `chat` | OpenRouter | Free tier assistant |
+| `assistant-gitmcp` | `mcp/` | `mcp-tool` + `chat` | Google + MCP | Documentation assistant via GitMCP |
+| `business-analyzer` | `google-business/` | `google-business` + `llm` | Google | Business reviews analyzer |
+| `newsletter-signup` | `marketing/` | `llm` + `notion` | Google | Lead capture with Notion |
+| `text-generator` | `utility/` | `llm` | Google | Text generation |
+| `multi-step-assistant` | `examples/` | `call-agent` + `llm` | Google | 4-step pipeline |
+
+**Agent Categories:**
+
+| Category | Folder | Description |
+|----------|--------|-------------|
+| Chat | `chat/` | Streaming chat assistants (different providers) |
+| MCP | `mcp/` | MCP server integrations (GitMCP, Context7) |
+| Google Business | `google-business/` | Google Business Profile API agents |
+| Marketing | `marketing/` | Lead capture, newsletters, CRM |
+| Utility | `utility/` | General-purpose tools |
+| Examples | `examples/` | Demo pipelines |
 
 **Resolution Order:**
 1. User agents (`src/agents/*.yaml`) — allows override
-2. Built-in agents (package) — fallback
+2. Built-in agents (package, via `BUILTIN_AGENT_PATHS` map) — fallback
 
 ---
 

package/docs/prd/requirements.md

@@ -8,7 +8,7 @@
   - `stream: true` → returns `Response` from `streamText`
   - `stream: false` → returns JSON object from `generateText`
 - **FR4:** The executor MUST immediately return a `Response` when a primitive returns a stream
-- **FR5:** The system MUST resolve variables using `$input.*` and `$stepResult.*` syntax
+- **FR5:** The system MUST resolve variables using `$input.*`, `$stepResult.*`, and `$env.*` syntax
 - **FR6:** The `output-generator` primitive MUST perform deterministic JSON transformation without LLM calls
 - **FR7:** The `call-agent` primitive MUST allow recursive invocation of other YAML workflow files
 - **FR8:** The system MUST expose a REST endpoint (`POST /api/beddel/chat`) for chat interactions

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "beddel",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "description": "Declarative Sequential Pipeline Executor for YAML workflows with native streaming and Vercel AI SDK v6 support",
     "author": "Bota na Rede",
     "license": "MIT",
@@ -31,7 +31,7 @@
     },
     "scripts": {
         "build": "tsc && npm run copy-agents",
-        "copy-agents": "cp -r src/agents/*.yaml dist/agents/",
+        "copy-agents": "rsync -av --include='*/' --include='*.yaml' --exclude='*' src/agents/ dist/agents/",
         "dev": "tsc --watch"
     },
     "dependencies": {

package/src/agents/{business-analyzer.yaml → google-business/business-analyzer.yaml}

@@ -13,8 +13,9 @@
 
 metadata:
   name: "Business Analyzer"
-  version: "1.0.0"
+  version: "1.1.0"
   description: "Analyzes business reviews and generates actionable insights"
+  builtin: true
 
 workflow:
   # Step 1: Fetch all reviews with auto-pagination
@@ -46,20 +47,28 @@ workflow:
         5. Trend analysis comparing recent vs older reviews
         6. Actionable recommendations
         
-        Format your response as structured JSON.
+        Return ONLY valid JSON (no markdown, no ```):
+        {
+          "sentimentScore": 8,
+          "positiveThemes": [{"theme": "Great service", "count": 15}],
+          "improvementAreas": [{"area": "Wait times", "count": 5}],
+          "urgentReviews": [{"reviewId": "xxx", "rating": 1, "issue": "summary"}],
+          "trendAnalysis": "Recent reviews show improvement...",
+          "recommendations": ["Focus on...", "Consider..."]
+        }
       messages:
         - role: "user"
-          content: |
-            Analyze these business reviews:
-            
-            Total Reviews: $stepResult.reviewsData.totalReviewCount
-            Average Rating: $stepResult.reviewsData.averageRating
-            
-            Reviews Data:
-            $stepResult.reviewsData.reviews
+          content: "$input.reviewsPayload"
+    result: "analysisRaw"
+
+  # Step 3: Parse analysis JSON
+  - id: "parse-analysis"
+    type: "output-generator"
+    config:
+      json: "$stepResult.analysisRaw.text"
     result: "analysis"
 
-  # Step 3: Generate response suggestions for negative reviews
+  # Step 4: Generate response suggestions for negative reviews
   - id: "generate-responses"
     type: "llm"
     config:
@@ -76,24 +85,29 @@ workflow:
         - Keep responses under 150 words
         - Be specific to the complaint mentioned
         
-        Format as JSON array with reviewId and suggestedResponse.
+        Return ONLY valid JSON array (no markdown, no ```):
+        [{"reviewId": "xxx", "rating": 2, "originalComment": "...", "suggestedResponse": "..."}]
+        
+        If no negative reviews, return: []
       messages:
         - role: "user"
-          content: |
-            Generate response suggestions for these reviews:
-            $stepResult.reviewsData.reviews
-    result: "responseSuggestions"
+          content: "$input.reviewsPayload"
+    result: "responsesRaw"
 
-  # Step 4: Compile final report
-  - id: "compile-report"
+  # Step 5: Parse responses JSON
+  - id: "parse-responses"
     type: "output-generator"
     config:
-      template:
-        summary:
-          totalReviews: "$stepResult.reviewsData.totalReviewCount"
-          averageRating: "$stepResult.reviewsData.averageRating"
-          analysisDate: "$input.analysisDate"
-        analysis: "$stepResult.analysis.text"
-        responseSuggestions: "$stepResult.responseSuggestions.text"
-        rawReviews: "$stepResult.reviewsData.reviews"
-    result: "finalReport"
+      json: "$stepResult.responsesRaw.text"
+    result: "responseSuggestions"
+
+# Explicit Return: Define the API response contract
+return:
+  success: true
+  summary:
+    totalReviews: "$stepResult.reviewsData.totalReviewCount"
+    averageRating: "$stepResult.reviewsData.averageRating"
+    pagesFetched: "$stepResult.reviewsData.data.pagesFetched"
+  analysis: "$stepResult.analysis"
+  responseSuggestions: "$stepResult.responseSuggestions"
+  reviews: "$stepResult.reviewsData.reviews"

package/src/agents/index.ts

@@ -3,6 +3,14 @@
  * 
  * Lists all agents bundled with the beddel package.
  * These are available automatically without user configuration.
+ * 
+ * Agents are organized by category:
+ * - chat/         Streaming chat assistants (different providers)
+ * - mcp/          MCP server integrations (GitMCP, Context7, etc.)
+ * - google-business/  Google Business Profile agents
+ * - marketing/    Lead capture, newsletters, CRM
+ * - utility/      General-purpose tools
+ * - examples/     Demo pipelines showing multi-step workflows
  */
 
 import { fileURLToPath } from 'url';
@@ -12,20 +20,37 @@ import { dirname, join } from 'path';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * Built-in agent definitions with their category paths
+ */
+export const BUILTIN_AGENT_PATHS: Record<string, string> = {
+  // Chat assistants
+  'assistant': 'chat/assistant.yaml',
+  'assistant-bedrock': 'chat/assistant-bedrock.yaml',
+  'assistant-openrouter': 'chat/assistant-openrouter.yaml',
+  
+  // MCP integrations
+  'assistant-gitmcp': 'mcp/assistant-gitmcp.yaml',
+  
+  // Google Business
+  'business-analyzer': 'google-business/business-analyzer.yaml',
+  
+  // Marketing
+  'newsletter-signup': 'marketing/newsletter-signup.yaml',
+  
+  // Utility
+  'text-generator': 'utility/text-generator.yaml',
+  
+  // Examples
+  'multi-step-assistant': 'examples/multi-step-assistant.yaml',
+};
+
 /**
  * List of built-in agent IDs available in the package
  */
-export const BUILTIN_AGENTS = [
-  'assistant',
-  'assistant-bedrock', 
-  'assistant-openrouter',
-  'assistant-gitmcp',
-  'text-generator',
-  'multi-step-assistant',
-  'business-analyzer',
-] as const;
+export const BUILTIN_AGENTS = Object.keys(BUILTIN_AGENT_PATHS) as readonly string[];
 
-export type BuiltinAgentId = typeof BUILTIN_AGENTS[number];
+export type BuiltinAgentId = keyof typeof BUILTIN_AGENT_PATHS;
 
 /**
  * Get the absolute path to the built-in agents directory
@@ -38,12 +63,37 @@ export function getBuiltinAgentsPath(): string {
  * Check if an agent ID is a built-in agent
  */
 export function isBuiltinAgent(agentId: string): agentId is BuiltinAgentId {
-  return BUILTIN_AGENTS.includes(agentId as BuiltinAgentId);
+  return agentId in BUILTIN_AGENT_PATHS;
 }
 
 /**
  * Get the full path to a built-in agent YAML file
  */
-export function getBuiltinAgentPath(agentId: BuiltinAgentId): string {
-  return join(__dirname, `${agentId}.yaml`);
+export function getBuiltinAgentPath(agentId: string): string | null {
+  const relativePath = BUILTIN_AGENT_PATHS[agentId];
+  if (!relativePath) return null;
+  return join(__dirname, relativePath);
+}
+
+/**
+ * Get all agents in a specific category
+ */
+export function getAgentsByCategory(category: string): string[] {
+  return Object.entries(BUILTIN_AGENT_PATHS)
+    .filter(([_, path]) => path.startsWith(`${category}/`))
+    .map(([id]) => id);
 }
+
+/**
+ * Available categories
+ */
+export const AGENT_CATEGORIES = [
+  'chat',
+  'mcp', 
+  'google-business',
+  'marketing',
+  'utility',
+  'examples',
+] as const;
+
+export type AgentCategory = typeof AGENT_CATEGORIES[number];

package/src/agents/marketing/newsletter-signup.yaml

@@ -0,0 +1,106 @@
+# Newsletter Signup Agent
+# Registers users to the newsletter with AI analysis and saves to Notion
+#
+# Required Environment Variables:
+# - NOTION_TOKEN (Internal Integration Secret)
+# - NOTION_DATABASE_ID (Database ID for newsletter signups)
+# - GEMINI_API_KEY (for AI analysis)
+#
+# Input:
+# - name: User's name
+# - email: User's email
+# - message: Optional message from user
+# - createdAt: ISO date string
+
+metadata:
+  name: "Newsletter Signup Agent"
+  version: "1.3.0"
+  description: "Registers users to the newsletter with AI analysis and saves to Notion"
+  builtin: true
+
+workflow:
+  # Step 1: Analyze user profile and generate structured JSON
+  - id: "analyze-user"
+    type: "llm"
+    config:
+      provider: "google"
+      model: "gemini-2.0-flash-exp"
+      system: |
+        You are a lead analyst for a technology newsletter.
+        
+        Analyze the user data and return ONLY a valid JSON (no markdown, no ```):
+        {
+          "tags": [{"name": "Tag1"}],
+          "sentiment": {"name": "Positive"},
+          "summary": "One-line summary"
+        }
+        
+        IMPORTANT RULES:
+        - tags: Array of objects with "name". Allowed values: "Support", "Sales", "Partnership", "Feedback"
+        - sentiment: Object with "name". Allowed values: "Positive", "Neutral", "Negative"
+        - summary: Short summary string (maximum 100 characters)
+        
+        Example for a positive message about the product:
+        {"tags": [{"name": "Feedback"}], "sentiment": {"name": "Positive"}, "summary": "User praises the product"}
+        
+        If there is no significant message:
+        {"tags": [{"name": "Feedback"}], "sentiment": {"name": "Neutral"}, "summary": "New newsletter subscriber"}
+        
+        Return ONLY the JSON, nothing else.
+      messages:
+        - role: "user"
+          content: |
+            Name: $input.name
+            Email: $input.email
+            Message: $input.message
+    result: "userAnalysis"
+
+  # Step 2: Parse the JSON from LLM
+  - id: "parse-analysis"
+    type: "output-generator"
+    config:
+      json: "$stepResult.userAnalysis.text"
+    result: "parsedAnalysis"
+
+  # Step 3: Create Notion page with structured data
+  - id: "create-notion-entry"
+    type: "notion"
+    config:
+      action: "createPage"
+      parent:
+        type: "database_id"
+        database_id: "$env.NOTION_DATABASE_ID"
+      properties:
+        Name:
+          title:
+            - text:
+                content: "$input.name"
+        Email:
+          email: "$input.email"
+        Message:
+          rich_text:
+            - text:
+                content: "$input.message"
+        Summary:
+          rich_text:
+            - text:
+                content: "$stepResult.parsedAnalysis.summary"
+        Tags:
+          multi_select: "$stepResult.parsedAnalysis.tags"
+        Sentiment:
+          select: "$stepResult.parsedAnalysis.sentiment"
+        CreatedAt:
+          date:
+            start: "$input.createdAt"
+    result: "notionResult"
+
+# Explicit Return: Define the API response contract
+return:
+  success: true
+  message: "Registration completed successfully!"
+  notionPageId: "$stepResult.notionResult.pageId"
+  notionUrl: "$stepResult.notionResult.url"
+  analysis:
+    tags: "$stepResult.parsedAnalysis.tags"
+    sentiment: "$stepResult.parsedAnalysis.sentiment"
+    summary: "$stepResult.parsedAnalysis.summary"

package/src/server/handler.ts

@@ -3,7 +3,7 @@ import { loadYaml } from '../core/parser';
 import { WorkflowExecutor } from '../core/workflow';
 import { join, normalize } from 'path';
 import { access } from 'fs/promises';
-import { getBuiltinAgentsPath } from '../agents';
+import { getBuiltinAgentPath } from '../agents';
 
 export interface BeddelHandlerOptions {
     /** Path to user-defined agents (relative to CWD). Default: 'src/agents' */
@@ -57,10 +57,10 @@ async function resolveAgentPath(
         return userPath;
     }
 
-    // 2. Fallback: built-in agents from package
+    // 2. Fallback: built-in agents from package (supports subfolder structure)
     if (!disableBuiltinAgents) {
-        const builtinPath = join(getBuiltinAgentsPath(), `${agentId}.yaml`);
-        if (await fileExists(builtinPath)) {
+        const builtinPath = getBuiltinAgentPath(agentId);
+        if (builtinPath && await fileExists(builtinPath)) {
             return builtinPath;
         }
     }