@jiggai/recipes 0.4.34 → 0.4.36

package/docs/TEMPLATE_VARIABLES.md

@@ -0,0 +1,196 @@
+# Template Variables
+
+ClawRecipes supports powerful template variable substitution for workflow prompts, file paths, and content. Variables use double-brace syntax: `{{variable.name}}`.
+
+## Global Variables
+
+These variables are available in all nodes:
+
+- `{{date}}` — Current ISO timestamp (e.g., `2025-04-04T03:53:00.000Z`)
+- `{{run.id}}` — Unique run ID (timestamp-based, e.g., `2025-04-04T03-53-00-123Z`)
+- `{{run.timestamp}}` — Alias for `{{run.id}}`
+- `{{workflow.id}}` — Workflow ID from the JSON file
+- `{{workflow.name}}` — Workflow display name (fallback to ID or filename)
+- `{{node.id}}` — Current node ID (available in media nodes)
+
+## Upstream Node Variables
+
+Access outputs from previous workflow nodes using the pattern `{{nodeId.fieldName}}`:
+
+### Basic Access Patterns
+
+- `{{nodeId.output}}` — Full JSON output envelope from the node
+- `{{nodeId.text}}` — The `text` field from the node output (most common)
+- `{{nodeId.fieldName}}` — Any specific field from the node output JSON
+
+### Common Pitfall: output vs text
+
+**Wrong:** `{{brand_review.output}}` returns the full envelope:
+```json
+{
+  "runId": "2025-04-04T03-53-00-123Z",
+  "teamId": "marketing-team",
+  "nodeId": "brand_review",
+  "kind": "llm",
+  "text": "Here is my review...",
+  "completedAt": "2025-04-04T03:53:15.000Z"
+}
+```
+
+**Right:** `{{brand_review.text}}` returns just the payload:
+```
+Here is my review...
+```
+
+## Nested JSON Extraction
+
+When a node's `text` field contains JSON, ClawRecipes automatically extracts nested fields:
+
+### Example Node Output
+```json
+{
+  "text": "{\"title\": \"Product Launch\", \"tags\": [\"marketing\"], \"approved\": true}"
+}
+```
+
+### Available Template Variables
+- `{{nodeId.text}}` — Raw JSON string
+- `{{nodeId.title}}` — Extracted: "Product Launch"  
+- `{{nodeId.approved_json}}` — For non-string values: "true"
+
+### Deeply Nested Extraction
+If the JSON contains nested objects, fields are flattened:
+
+```json
+{
+  "text": "{\"meta\": {\"author\": \"John\", \"priority\": 1}}"
+}
+```
+
+Available as:
+- `{{nodeId.meta_json}}` — Full meta object as JSON string
+- `{{nodeId.author}}` — "John" (if meta.author is a string)
+
+## LLM Node Structured Output
+
+LLM nodes with `outputFields` configuration produce predictable JSON structures:
+
+### Configuration
+```json
+{
+  "config": {
+    "outputFields": [
+      {"name": "title", "type": "text"},
+      {"name": "tags", "type": "list"}, 
+      {"name": "metadata", "type": "json"}
+    ]
+  }
+}
+```
+
+### Template Access
+```
+Title: {{nodeId.title}}
+Tags: {{nodeId.tags}}  
+Metadata: {{nodeId.metadata_json}}
+```
+
+## Usage Examples
+
+### LLM Prompt Template
+```
+Review the content from the previous step:
+
+{{brand_review.text}}
+
+Based on this review, create a social media post with:
+- Title: engaging and on-brand
+- Content: max 280 characters
+- Hashtags: 3-5 relevant tags
+
+Current date: {{date}}
+Workflow: {{workflow.name}}
+```
+
+### File Path Templates
+```json
+{
+  "tool": "fs.write",
+  "args": {
+    "path": "content/{{run.id}}/{{brand_review.title}}.md",
+    "content": "# {{brand_review.title}}\n\n{{brand_review.text}}"
+  }
+}
+```
+
+### Media Node Prompts
+```json
+{
+  "config": {
+    "promptTemplate": "Create an image for: {{content_draft.title}}\n\nStyle: {{brand_review.style}}\nMood: professional and engaging"
+  }
+}
+```
+
+## Implementation Details
+
+Template substitution happens in the workflow worker during node execution. The code path is:
+
+- **Primary**: `src/lib/workflows/workflow-worker.ts` — `buildTemplateVars()` function
+- **Utility**: `src/lib/workflows/workflow-utils.ts` — `templateReplace()` function
+
+### Variable Resolution Process
+
+1. **Global vars** are built from run metadata and timestamps
+2. **Node outputs** are loaded from each completed node's output file
+3. **JSON parsing** attempts to extract fields from the `text` field
+4. **Nested extraction** flattens nested objects with `_json` suffixes for non-strings
+5. **Template replacement** applies all variables using simple string substitution
+
+### Performance Notes
+
+- Variables are rebuilt for each node execution (fresh state)
+- Large node outputs are fully loaded into memory during template resolution
+- JSON parsing failures are silently ignored (graceful degradation)
+
+## Best Practices
+
+### Variable Naming
+- Use descriptive node IDs: `brand_review` not `step1`
+- Design consistent output field names across nodes
+- Use `outputFields` for structured LLM outputs
+
+### Error Handling
+- Always provide fallbacks: `{{nodeId.title || "Untitled"}}`  
+- Test templates with missing/malformed node outputs
+- Use `{{nodeId.text}}` when unsure about field structure
+
+### Memory Management
+- Avoid extremely large text outputs in frequently-referenced nodes
+- Consider splitting large data into separate file outputs
+
+## Common Patterns
+
+### Content Pipeline
+```
+1. research_node.text → "Market analysis shows..."
+2. draft_node template: "Based on {{research_node.text}}, write..."
+3. review_node template: "Review this draft: {{draft_node.text}}"
+```
+
+### Conditional Content
+```
+{% if brand_review.approved %}
+Approved content: {{brand_review.text}}
+{% else %}
+Needs revision: {{brand_review.feedback}}
+{% endif %}
+```
+
+Note: ClawRecipes uses simple string substitution, not template engines like Jinja2. Complex conditionals should be handled in LLM prompts.
+
+## Related Documentation
+
+- [WORKFLOW_NODES.md](WORKFLOW_NODES.md) — Node types and configuration
+- [WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md) — Template usage examples
+- [MEDIA_GENERATION.md](MEDIA_GENERATION.md) — Media node templates and variables

package/docs/WORKFLOW_APPROVALS.md

@@ -0,0 +1,334 @@
+# Workflow Approvals
+
+Human approval nodes (`human_approval`) pause workflow execution for manual review. This document covers the runtime behavior, state management, and approval flow.
+
+## Approval Flow Overview
+
+1. **Node Execution** — Worker reaches approval node
+2. **Pause State** — Run status changes to `awaiting_approval`
+3. **Message Sent** — Approval request sent to configured channel
+4. **Human Decision** — User replies with approve/decline command
+5. **State Update** — Approval recorded to disk
+6. **Resume** — Workflow continues or loops back for revision
+
+## Runtime Behavior
+
+### Node Status Transition
+
+When a workflow worker processes a `human_approval` node:
+
+```
+node.status: undefined → waiting → waiting_approval
+run.status: running → awaiting_approval
+```
+
+The worker:
+1. Creates approval directory: `workflow-runs/{runId}/approvals/`
+2. Generates random approval code (6-char uppercase)
+3. Writes `approval.json` with pending status
+4. Sends message to configured channel with approval code
+5. Marks node as waiting in run state
+6. Pauses execution (no further nodes enqueued)
+
+### State Files Written
+
+**Run Log Update** (`workflow-runs/{runId}/run.json`):
+```json
+{
+  "status": "awaiting_approval",
+  "nodeStates": {
+    "approval_node": {"status": "waiting", "ts": "2025-04-04T03:53:15.000Z"}
+  },
+  "events": [
+    {
+      "ts": "2025-04-04T03:53:15.000Z", 
+      "type": "node.awaiting_approval",
+      "nodeId": "approval_node",
+      "bindingId": "telegram:account:mybot",
+      "approvalFile": "workflow-runs/2025-04-04T03-53-00-123Z/approvals/approval.json"
+    }
+  ],
+  "nodeResults": [
+    {
+      "nodeId": "approval_node",
+      "kind": "human_approval", 
+      "approvalBindingId": "telegram:account:mybot",
+      "approvalFile": "workflow-runs/2025-04-04T03-53-00-123Z/approvals/approval.json"
+    }
+  ]
+}
+```
+
+**Approval Record** (`workflow-runs/{runId}/approvals/approval.json`):
+```json
+{
+  "runId": "2025-04-04T03-53-00-123Z",
+  "teamId": "marketing-team",
+  "workflowFile": "content-pipeline.workflow.json",
+  "nodeId": "approval_node",
+  "bindingId": "telegram:account:mybot",
+  "requestedAt": "2025-04-04T03:53:15.000Z",
+  "status": "pending",
+  "code": "XY4K91",
+  "ticket": "work/in-progress/0042-social-media-campaign.md",
+  "runLog": "workflow-runs/2025-04-04T03-53-00-123Z/run.json"
+}
+```
+
+## Message Template Rendering
+
+The approval message includes template variable substitution:
+
+**Template Variables Available:**
+- `{{workflow.name}}` — Workflow display name
+- `{{code}}` — Generated approval code  
+- `{{ticket}}` — Relative path to ticket file
+- Proposed content preview (from prior node outputs)
+
+**Default Message Template:**
+```
+Approval requested: {{workflow.name}}
+Ticket: {{ticket}}
+Code: {{code}}
+
+---
+PROPOSED POST (X)
+---
+{{proposed_content}}
+
+Reply with:
+- approve {{code}}
+- decline {{code}} <what to change>
+
+(You can also review in Kitchen: http://localhost:7777/teams/{{teamId}}/workflows/{{workflow.id}})
+```
+
+**Proposed Content Logic:**
+1. Look for `qc_brand` node output first
+2. Fall back to most recent prior LLM node
+3. Extract `text` field and sanitize for preview
+4. Show "(Warning: no proposed text found)" if unavailable
+
+## Human Response Handling
+
+### Command Format
+
+Users reply in the configured channel:
+
+```
+approve XY4K91
+decline XY4K91 needs better headlines
+```
+
+**Parsing Rules:**
+- Case-insensitive verb matching: `approve|decline`
+- Code must be exact (uppercase)
+- Optional note after code for decline responses
+- Parser checks multiple lines, prefers last match
+
+### Auto-Processing
+
+When a user replies with a valid approval command:
+
+1. **Event Detection** — Plugin listener matches approval format
+2. **Code Lookup** — Searches all team runs for matching pending approval
+3. **Decision Recording** — Updates approval.json status and note
+4. **Auto-Resume** — Calls resume workflow to continue execution
+
+**Supported Channels:**
+- Telegram (primary)
+- Other channels with conditional processing based on metadata
+
+## Resume and Continuation
+
+### Approval Resume
+
+**Approved Flows:**
+```
+approval.status: pending → approved
+node.status: waiting → success  
+run.status: awaiting_approval → running
+→ Next node enqueued
+```
+
+**Rejection Flows:**
+```
+approval.status: pending → rejected
+node.status: waiting → error
+run.status: awaiting_approval → needs_revision
+→ Loop back to revision node
+```
+
+### Revision Logic
+
+When an approval is declined:
+
+1. **Find revision target** — Prefers `draft_assets` node, else closest prior LLM node
+2. **Clear node states** — Remove status for revision node onward
+3. **Clear locks** — Remove any stale node lock files  
+4. **Enqueue revision** — Send revision task to appropriate agent
+5. **Include feedback** — Pass human note in task packet
+
+**Revision Node Selection:**
+```typescript
+// Preferred: explicit draft_assets node
+let reviseIdx = workflow.nodes.findIndex(n => n.id === 'draft_assets');
+
+// Fallback: most recent LLM node before approval  
+if (reviseIdx < 0) {
+  for (let i = approvalIdx - 1; i >= 0; i--) {
+    if (workflow.nodes[i]?.kind === 'llm') {
+      reviseIdx = i;
+      break;
+    }
+  }
+}
+```
+
+## Configuration
+
+### Node Configuration
+
+```json
+{
+  "id": "final_approval",
+  "kind": "human_approval",
+  "action": {
+    "approvalBindingId": "telegram:account:mybot"
+  },
+  "config": {
+    "provider": "telegram",
+    "target": "6477250615",
+    "accountId": "mybot", 
+    "agentId": "marketing-team-lead"
+  }
+}
+```
+
+**Configuration Hierarchy:**
+1. `approvalBindingId` → Look up in OpenClaw config bindings
+2. `config.target` → Direct channel target
+3. Back-compat fallbacks for known account IDs
+
+### Agent Assignment
+
+Approval nodes are executed by:
+1. **Explicit `config.agentId`** — Workflow author override
+2. **Team lead** — `${teamId}-lead` (default orchestrator)  
+3. **Current agent** — Fallback for backwards compatibility
+
+## Command Line Interface
+
+### Manual Approval
+```bash
+openclaw recipes workflows approve \
+  --team-id marketing-team \
+  --run-id 2025-04-04T03-53-00-123Z \
+  --approved true
+
+openclaw recipes workflows approve \
+  --team-id marketing-team \
+  --run-id 2025-04-04T03-53-00-123Z \
+  --approved false \
+  --note "Headlines need work"
+```
+
+### Resume Workflow  
+```bash
+openclaw recipes workflows resume \
+  --team-id marketing-team \
+  --run-id 2025-04-04T03-53-00-123Z
+```
+
+### Poll Approvals
+```bash
+# Auto-resume any decided approvals
+openclaw recipes workflows poll-approvals \
+  --team-id marketing-team \
+  --limit 20
+```
+
+## Implementation Details
+
+### Code Locations
+
+**Primary Approval Logic:**
+- `src/lib/workflows/workflow-approvals.ts`
+  - `approveWorkflowRun()` — Record approval decision
+  - `resumeWorkflowRun()` — Continue/revise after decision
+  - `pollWorkflowApprovals()` — Auto-resume decided approvals
+
+**Worker Execution:**
+- `src/lib/workflows/workflow-worker.ts`
+  - Approval node execution in `runWorkflowWorkerTick()`
+  - Message sending and state management
+
+**Event Handling:**
+- `index.ts` — Auto-approval reply handler in plugin registration
+
+### File Structure
+```
+workspace-{teamId}/
+└── shared-context/
+    └── workflow-runs/
+        └── {runId}/
+            ├── run.json              # Main run state
+            ├── approvals/
+            │   └── approval.json     # Approval record
+            ├── locks/                # Node execution locks
+            └── node-outputs/         # Node result files
+```
+
+## Error Handling
+
+### Missing Targets
+```
+Node final_approval missing approval target (provide config.target or binding mapping)
+```
+
+**Solution:** Configure `config.target` or add binding in OpenClaw config.
+
+### Code Not Found
+```
+[recipes] approval reply not matched: code=XY4K91
+```
+
+**Causes:**
+- Code already processed/expired
+- Wrong team workspace searched  
+- Approval file corrupted
+
+### Resume Failures
+```
+Approval still pending. Update approval.json first.
+```
+
+**Solution:** Record decision with `workflows approve` before resuming.
+
+## Best Practices
+
+### Node Placement
+- Place approval nodes after content generation but before publishing
+- Use descriptive node IDs: `final_approval`, `brand_review`, `legal_check`
+
+### Message Configuration  
+- Always configure approval binding in OpenClaw config for production
+- Test approval flow with known test accounts/channels
+- Include meaningful context in approval messages
+
+### Error Recovery
+- Monitor approval files for stuck `pending` status
+- Use `poll-approvals` for automated processing
+- Set up alerting for approval timeouts
+
+### Workflow Design
+- Design clear revision loops with identifiable `draft_assets` nodes
+- Keep approval criteria specific and actionable
+- Document approval responsibilities in team workflows
+
+## Related Documentation
+
+- [WORKFLOW_NODES.md](WORKFLOW_NODES.md) — All node types and configuration
+- [TEMPLATE_VARIABLES.md](TEMPLATE_VARIABLES.md) — Message template variables
+- [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md) — Publishing after approval
+- [COMMANDS.md](COMMANDS.md) — CLI workflow commands

package/docs/WORKFLOW_NODES.md

@@ -0,0 +1,147 @@
+# Workflow Node Reference (ClawRecipes)
+
+This document is the **runtime** reference for workflow node configuration in ClawRecipes.
+
+ClawKitchen (the UI) edits workflow JSON files, but the actual execution semantics live here.
+
+If you’re new to the file format, start with:
+- [WORKFLOW_RUNS_FILE_FIRST.md](WORKFLOW_RUNS_FILE_FIRST.md)
+
+---
+
+## Mental model
+
+A workflow run is a directory on disk containing a `run.json` (and logs/deliverables). The worker executes nodes in order, persists each node’s output, and downstream nodes reference upstream outputs via `{{ }}` template variables.
+
+### Template variables
+
+At runtime, ClawRecipes replaces `{{vars}}` in strings inside node configs.
+
+There are two broad categories:
+
+**Global vars** (always available):
+- `{{date}}`
+- `{{run.id}}`
+- `{{workflow.id}}`
+- `{{workflow.name}}`
+- `{{node.id}}`
+
+**Upstream node vars** (depend on prior nodes):
+- `{{someNode.output}}` — the full stored output envelope
+- `{{someNode.text}}` — the most common “payload string” field
+- `{{someNode.someField}}` — a field extracted from JSON inside the node’s `text` (when applicable)
+
+Notes:
+- If an upstream node stores JSON inside its `text` field, the template system can extract nested fields (e.g. `{{draft_assets.video_brief}}`).
+- If you see “garbled JSON” showing up in a media prompt, you’re usually templating the *envelope* (e.g. `{{draft_assets.output}}`) instead of the intended field (e.g. `{{draft_assets.text}}` or `{{draft_assets.video_brief}}`).
+
+---
+
+## Node types
+
+This section describes the important node types and the config fields the worker actually reads.
+
+### LLM nodes
+
+LLM nodes execute via the `llm-task` tool.
+
+Common config fields (stored under `node.config`):
+- `promptTemplate` (string): the prompt content, after template-var substitution
+- `timeoutMs` (number, optional)
+- `model` (string, optional): provider/model selection (node → workflow → global precedence)
+
+#### outputFields (structured output)
+
+If `node.config.outputFields` is present, ClawRecipes will:
+1) Append an explicit OUTPUT FORMAT section to the prompt
+2) Derive a JSON Schema and pass it to `llm-task`
+
+That means the LLM output is **validated**.
+
+Shape:
+
+```json
+{
+  "outputFields": [
+    {"name": "summary", "type": "text"},
+    {"name": "angles", "type": "list"},
+    {"name": "metadata", "type": "json"}
+  ]
+}
+```
+
+Types:
+- `text` → JSON string
+- `list` → array of strings
+- `json` → JSON object
+
+---
+
+### Media nodes (image/video/audio)
+
+Media nodes ultimately produce a file deliverable. ClawRecipes invokes a **MediaDriver** selected by `provider`.
+
+Provider selection:
+- In workflow JSON, providers are referenced as `skill-<slug>`
+- At runtime the worker strips `skill-` and looks up a driver by slug
+
+#### Common media config fields
+
+These are passed through to drivers as `opts.config`:
+
+- `size` (string):
+  - For images, typically pixel size like `1024x1024`, `1792x1024`, `1024x1792`
+  - Some providers interpret this differently (drivers may map pixel sizes to tiers)
+
+- `duration` (string or number): duration in seconds, e.g. `"5s"`, `"10s"`, or `10`
+
+- `aspect_ratio` (string): e.g. `"16:9"`, `"9:16"` (provider-specific)
+
+- `quality` / `style`: image-provider-specific fields (ex: OpenAI)
+
+- `addRefinement` (boolean): **opt-in** prompt refinement pass for video/audio.
+  - Default is OFF. When enabled, the worker runs an extra `llm-task` call to refine the prompt before invoking the driver.
+
+#### Driver constraints
+
+Drivers can optionally declare duration constraints (`minSeconds/maxSeconds/defaultSeconds`).
+
+Kitchen surfaces these constraints as UX hints, but the runtime is the source of truth.
+
+---
+
+### Tool nodes
+
+Tool nodes call a tool by name with JSON args. Example:
+- `fs.append`
+- `outbound.post`
+- `message.send`
+
+Tool nodes support template vars inside string args.
+
+---
+
+### Human approval nodes
+
+Human approval nodes pause execution until an approval is granted in the UI.
+
+Common pattern:
+- Upstream LLM generates a draft
+- Approval node shows a `messageTemplate` (with template vars)
+- Downstream nodes continue only after approval
+
+---
+
+## Adding new capabilities (where to change code)
+
+- LLM output shaping/validation: `src/lib/workflows/workflow-worker.ts`
+- Media providers: `src/lib/workflows/media-drivers/`
+- CLI for Kitchen dropdown: `openclaw recipes workflows media-drivers` (handler: `src/handlers/media-drivers.ts`)
+
+---
+
+## Troubleshooting quick hits
+
+- **Provider missing in dropdown**: run `openclaw recipes workflows media-drivers` and check `available` / `missingEnvVars`.
+- **Media node ignores config**: confirm the driver reads `opts.config` (not all scripts support every knob).
+- **Bad video quality**: ensure your prompt is a single clear scene brief; avoid multi-scene paragraphs when the provider needs a seed frame.

package/docs/WORKFLOW_RUNS_FILE_FIRST.md

@@ -3,6 +3,8 @@
 This document explains how ClawRecipes workflows work in practice.
 
 If you want a copy-paste cookbook after reading this reference, also see:
+
+- [WORKFLOW_NODES.md](WORKFLOW_NODES.md) — runtime node config reference (LLM/media/tool/approval)
 - [WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md)
 
 If you are trying to answer any of these questions, start here:

package/index.ts

@@ -47,6 +47,7 @@ import { handleScaffold, scaffoldAgentFromRecipe } from "./src/handlers/scaffold
 import { handleAddRoleToTeam } from "./src/handlers/team-add-role";
 import { reconcileRecipeCronJobs } from "./src/handlers/cron";
 import { handleWorkflowsApprove, handleWorkflowsPollApprovals, handleWorkflowsResume, handleWorkflowsRun, handleWorkflowsRunnerOnce, handleWorkflowsRunnerTick, handleWorkflowsWorkerTick } from "./src/handlers/workflows";
+import { handleMediaDriversList } from "./src/handlers/media-drivers";
 import { listRecipeFiles, loadRecipeById, workspacePath } from "./src/lib/recipes";
 import {
   executeWorkspaceCleanup,
@@ -728,6 +729,14 @@ workflows
             console.log(JSON.stringify(res, null, 2));
           });
 
+        workflows
+          .command("media-drivers")
+          .description("List available media generation drivers with env-var availability")
+          .action(async () => {
+            const drivers = await handleMediaDriversList();
+            console.log(JSON.stringify(drivers));
+          });
+
         workflows
           .command("poll-approvals")
           .description("Auto-resume any workflow runs whose approval decision has been recorded (approved/rejected)")