@jiggai/recipes 0.4.18 → 0.4.19

package/docs/WORKFLOW_RUNS_FILE_FIRST.md

@@ -2,8 +2,15 @@
 
 This document explains how ClawRecipes workflows work in practice.
 
+If you want a copy-paste cookbook after reading this reference, also see:
+- [WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md)
+
 If you are trying to answer any of these questions, start here:
 - Where do workflow files live?
+- What node types are available?
+- What do triggers do?
+- What is a run?
+- How do edges work?
 - How do I run one manually?
 - What does the runner do?
 - What does the worker do?
@@ -44,6 +51,448 @@ Example:
 
 ---
 
+## What a workflow file looks like
+
+At a high level, a workflow file contains:
+- workflow metadata (`id`, optional `name`)
+- optional `triggers`
+- `nodes`
+- optional `edges`
+
+Minimal example:
+
+```json
+{
+  "id": "demo",
+  "name": "Simple demo",
+  "nodes": [
+    { "id": "start", "kind": "start" },
+    {
+      "id": "append_log",
+      "kind": "tool",
+      "assignedTo": { "agentId": "development-team-lead" },
+      "action": {
+        "tool": "fs.append",
+        "args": {
+          "path": "shared-context/APPEND_LOG.md",
+          "content": "- run={{run.id}}\n"
+        }
+      }
+    },
+    { "id": "end", "kind": "end" }
+  ],
+  "edges": [
+    { "from": "start", "to": "append_log", "on": "success" },
+    { "from": "append_log", "to": "end", "on": "success" }
+  ]
+}
+```
+
+---
+
+## Available workflow node types
+
+These are the **current first-class node kinds** supported by the runner.
+
+### Quick chooser
+
+Use this when you are deciding what kind of node to add:
+
+- use **`start`** when you want a visible graph entry point
+- use **`end`** when you want a visible graph exit point
+- use **`llm`** when you want the workflow to generate or transform content with an LLM
+- use **`tool`** when you want the workflow to call a tool or side-effecting action
+- use **`human_approval`** when a person must approve before the workflow continues
+- use **`writeback`** when you want to append workflow breadcrumbs/results into team files
+
+### `start`
+Purpose:
+- visual or structural start node
+- useful in UI-authored workflows
+- treated as a no-op by the runner
+
+What it does at runtime:
+- marks itself successful
+- does not perform work
+
+Example:
+
+```json
+{ "id": "start", "kind": "start" }
+```
+
+### `end`
+Purpose:
+- visual or structural end node
+- used to make the workflow graph readable
+- treated as a no-op by the runner
+
+What it does at runtime:
+- marks itself successful
+- does not perform work
+
+Example:
+
+```json
+{ "id": "end", "kind": "end" }
+```
+
+### `llm`
+Purpose:
+- run an LLM step in the workflow
+- generate structured or text-like content and store it as node output JSON
+
+Use it when:
+- you want to draft content
+- you want to transform or summarize earlier node output
+- you want a workflow step to reason over previous results before the next action
+
+Required pieces:
+- `assignedTo.agentId`
+- either `action.promptTemplatePath` or `action.promptTemplate`
+
+What it does:
+- builds a task prompt
+- calls `llm-task-fixed` if present, otherwise falls back to `llm-task`
+- passes upstream node output when available
+- writes result JSON into the run’s `node-outputs/`
+
+Example using an inline prompt:
+
+```json
+{
+  "id": "draft_post",
+  "kind": "llm",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "promptTemplate": "Write a short product update for X announcing the new workflow runner."
+  }
+}
+```
+
+Example using a prompt template file:
+
+```json
+{
+  "id": "draft_post",
+  "kind": "llm",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "promptTemplatePath": "shared-context/prompts/draft-post.md"
+  }
+}
+```
+
+Optional output path override:
+
+```json
+{
+  "id": "draft_post",
+  "kind": "llm",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "promptTemplate": "Write a short changelog entry."
+  },
+  "output": {
+    "path": "node-outputs/custom-draft.json"
+  }
+}
+```
+
+### `tool`
+Purpose:
+- run a tool action during the workflow
+
+Use it when:
+- you want to write a file
+- send a message
+- publish content
+- call another tool after an LLM step
+
+Current behavior:
+- supports runner-native special handling for some tools
+- otherwise falls back to normal tool invocation by tool name
+- stores result/error artifacts in `artifacts/`
+
+Currently important built-in / special-cased tools:
+
+#### `fs.append`
+Use when you want to append text into a file in the team workspace.
+
+Required args:
+- `path`
+- `content`
+
+Example:
+
+```json
+{
+  "id": "append_log",
+  "kind": "tool",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "tool": "fs.append",
+    "args": {
+      "path": "shared-context/APPEND_LOG.md",
+      "content": "- {{date}} run={{run.id}}\n"
+    }
+  }
+}
+```
+
+Notes:
+- path must stay within the team workspace
+- simple template vars are supported in args like `{{date}}`, `{{run.id}}`, `{{workflow.id}}`
+
+#### `outbound.post`
+Use when you want a workflow to publish externally through the supported outbound posting service.
+
+Required args:
+- `platform`
+- `text`
+- `idempotencyKey`
+
+Required plugin config:
+- `outbound.baseUrl`
+- `outbound.apiKey`
+
+Example:
+
+```json
+{
+  "id": "publish_x",
+  "kind": "tool",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "tool": "outbound.post",
+    "args": {
+      "platform": "x",
+      "text": "Hello from ClawRecipes",
+      "idempotencyKey": "{{run.id}}:publish_x",
+      "runContext": {
+        "teamId": "development-team",
+        "workflowId": "marketing",
+        "workflowRunId": "{{run.id}}",
+        "nodeId": "publish_x"
+      }
+    }
+  }
+}
+```
+
+For full posting details, see [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md).
+
+#### Other tool names
+If a tool node references some other tool name, the runner will try to invoke that tool by name.
+
+Example:
+
+```json
+{
+  "id": "some_tool_step",
+  "kind": "tool",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "tool": "message",
+    "args": {
+      "action": "send",
+      "channel": "telegram",
+      "target": "123456",
+      "message": "Workflow says hello"
+    }
+  }
+}
+```
+
+Whether that works depends on your actual runtime/tool exposure.
+
+### `human_approval`
+Purpose:
+- pause a workflow until a human approves or rejects
+
+Use it when:
+- the workflow might publish externally
+- a human needs to review copy or generated content
+- the next step is risky enough that you do not want it to happen automatically
+
+Required pieces:
+- `assignedTo.agentId`
+- `action.approvalBindingId` (or workflow-level fallback metadata that resolves to one)
+
+What it does:
+- writes `approvals/approval.json`
+- sends an approval request message through the bound messaging target
+- changes run status to `awaiting_approval`
+- waits until you record a decision
+
+Example:
+
+```json
+{
+  "id": "approval",
+  "kind": "human_approval",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "approvalBindingId": "marketing-approval"
+  }
+}
+```
+
+### `writeback`
+Purpose:
+- append workflow run information back into one or more workspace files
+
+Use it when:
+- you want a durable audit note in `notes/` or `shared-context/`
+- you want workflow output to leave a breadcrumb for humans
+- you want the run to update a team file after the main work finishes
+
+Required pieces:
+- `assignedTo.agentId`
+- `action.writebackPaths[]`
+
+What it does:
+- appends a stamped workflow note with run/ticket context into the target file(s)
+
+Example:
+
+```json
+{
+  "id": "write_summary",
+  "kind": "writeback",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "writebackPaths": [
+      "notes/status.md",
+      "shared-context/last-run.md"
+    ]
+  }
+}
+```
+
+---
+
+## What is **not** currently a first-class built-in node type?
+
+People often expect nodes like:
+- `if`
+- `delay`
+- `switch`
+- `loop`
+
+Those are **not currently first-class built-in node kinds** in the runner code.
+
+So if you want branching today, use:
+- edges (`success`, `error`, `always`)
+- multiple nodes
+- approval or tool-mediated control flow
+
+If you want waiting/delay behavior today, do it outside the runner with:
+- cron triggers
+- scheduled reruns
+- approval pause/resume
+
+I’m calling this out explicitly so we don’t imply features that do not yet exist as first-class nodes.
+
+---
+
+## Triggers
+
+Triggers answer the question:
+
+**“What causes a workflow run to be created?”**
+
+In the current schema, a workflow may include `triggers[]`.
+
+Current workflow type shape:
+
+```json
+{
+  "kind": "cron",
+  "cron": "0 14 * * 1-5",
+  "tz": "America/New_York"
+}
+```
+
+### What is currently supported in the type layer?
+- `cron` is the clearly documented trigger kind in the current workflow types
+- manual runs are also supported operationally via CLI, even though that is a run-time invocation mode rather than a trigger stored in the workflow file
+
+### Example trigger block
+
+```json
+{
+  "id": "weekday-summary",
+  "triggers": [
+    {
+      "kind": "cron",
+      "cron": "0 14 * * 1-5",
+      "tz": "America/New_York"
+    }
+  ],
+  "nodes": [
+    { "id": "start", "kind": "start" },
+    { "id": "end", "kind": "end" }
+  ]
+}
+```
+
+Human translation of that example:
+- run on weekdays
+- at 2:00 PM
+- in New York time
+
+### Manual trigger example
+You can always create a run manually:
+
+```bash
+openclaw recipes workflows run \
+  --team-id development-team \
+  --workflow-file weekday-summary.workflow.json
+```
+
+---
+
+## Runs
+
+A **run** is one concrete execution of a workflow.
+
+If your workflow is the recipe, the run is the actual cooking session.
+
+### What a run records
+A run stores:
+- workflow id/name/file
+- team id
+- run id
+- trigger information
+- current run status
+- node states
+- event history
+- node results
+- ticket/lane context when used
+
+### Common run statuses you will see
+Examples include:
+- `queued` — the run exists and is waiting to be claimed
+- `running` — the runner/worker is actively moving it forward
+- `awaiting_approval` — the run is paused for human review
+- `completed` — the run finished successfully
+- `rejected` — approval was rejected and the run stopped there
+- `needs_revision` — a rejection pushed the run back into a revise-and-try-again path
+
+### Where a run lives
+
+```text
+shared-context/workflow-runs/<runId>/run.json
+```
+
+### What else is inside the run folder?
+- `node-outputs/` — output from nodes
+- `artifacts/` — tool result payloads
+- `approvals/approval.json` — approval state when needed
+
+---
+
 ## Where workflow runs live
 
 Every workflow run gets its own folder under:
@@ -76,6 +525,75 @@ Important files:
 
 ---
 
+## Edges
+
+Edges define how the workflow graph moves from one node to another.
+
+Current edge shape:
+
+```json
+{
+  "from": "draft_post",
+  "to": "approval",
+  "on": "success"
+}
+```
+
+### Supported `on` values
+- `success`
+- `error`
+- `always`
+
+### What they mean
+#### `success`
+Move to the target node if the source node completed successfully.
+
+```json
+{ "from": "draft_post", "to": "approval", "on": "success" }
+```
+
+#### `error`
+Move to the target node if the source node failed.
+
+```json
+{ "from": "publish_x", "to": "notify_failure", "on": "error" }
+```
+
+#### `always`
+Move to the target node whether the source node succeeded or failed.
+
+```json
+{ "from": "publish_x", "to": "write_summary", "on": "always" }
+```
+
+### Important current semantics
+The current runner behavior is intentionally simple:
+
+- if a node has explicit `input.from`, those dependencies behave like **AND**
+- if a node has incoming edges, edge satisfaction behaves like **OR**
+  - meaning: if **any** incoming edge condition is satisfied, the node can run
+
+Human translation:
+- `input.from` is "wait for all of these upstream node outputs"
+- incoming edges are "if any of these paths became valid, go ahead"
+
+That is important. Do not assume complex boolean graph semantics unless you have built them explicitly.
+
+### Example: success path + failure path
+
+```json
+{
+  "edges": [
+    { "from": "draft_post", "to": "approval", "on": "success" },
+    { "from": "draft_post", "to": "notify_failure", "on": "error" },
+    { "from": "approval", "to": "publish_x", "on": "success" },
+    { "from": "publish_x", "to": "write_summary", "on": "always" }
+  ]
+}
+```
+
+---
+
 ## The two moving parts: runner and worker
 
 ClawRecipes splits workflow execution into two roles.
@@ -255,6 +773,8 @@ So if a workflow runs but does not actually post, check your posting path before
 
 ## Typical end-to-end example
 
+This is the operational sequence most people mean when they say, "run the workflow":
+
 ```bash
 # 1) trigger a run
 openclaw recipes workflows run \
@@ -280,3 +800,58 @@ openclaw recipes workflows resume \
   --team-id development-team \
   --run-id <runId>
 ```
+
+---
+
+## End-to-end example: draft → approve → publish
+
+Use this pattern when you want:
+- an LLM to draft content
+- a human to approve it
+- a tool step to publish it only after approval
+
+```json
+{
+  "id": "marketing-demo",
+  "name": "Marketing demo",
+  "nodes": [
+    { "id": "start", "kind": "start" },
+    {
+      "id": "draft_post",
+      "kind": "llm",
+      "assignedTo": { "agentId": "development-team-lead" },
+      "action": {
+        "promptTemplate": "Write a short X post announcing our new workflow system."
+      }
+    },
+    {
+      "id": "approval",
+      "kind": "human_approval",
+      "assignedTo": { "agentId": "development-team-lead" },
+      "action": {
+        "approvalBindingId": "marketing-approval"
+      }
+    },
+    {
+      "id": "publish_x",
+      "kind": "tool",
+      "assignedTo": { "agentId": "development-team-lead" },
+      "action": {
+        "tool": "outbound.post",
+        "args": {
+          "platform": "x",
+          "text": "Hello from ClawRecipes",
+          "idempotencyKey": "demo:publish_x"
+        }
+      }
+    },
+    { "id": "end", "kind": "end" }
+  ],
+  "edges": [
+    { "from": "start", "to": "draft_post", "on": "success" },
+    { "from": "draft_post", "to": "approval", "on": "success" },
+    { "from": "approval", "to": "publish_x", "on": "success" },
+    { "from": "publish_x", "to": "end", "on": "success" }
+  ]
+}
+```

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "recipes",
   "name": "Recipes",
   "description": "Markdown recipes that scaffold agents and teams (workspace-local).",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",

package/src/lib/workflows/workflow-runner.ts

@@ -2069,11 +2069,62 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
 
 
         } else if (toolName === 'marketing.post_all') {
-          // Disabled by default: do not ship plugins that spawn local processes for posting.
-          // Use an approval-gated workflow node that calls a dedicated posting tool/plugin instead.
-          throw new Error(
-            'marketing.post_all is disabled in this build (install safety). Use an external posting tool/plugin (approval-gated) instead.'
-          );
+          // Local-only controller patch for RJ: re-enable X posting via xurl. Supports args.dryRun=true.
+          const { execFile } = await import('node:child_process');
+          const { promisify } = await import('node:util');
+          const execFileP = promisify(execFile);
+
+          const platforms = Array.isArray((toolArgs as Record<string, unknown>)?.['platforms'])
+            ? (((toolArgs as Record<string, unknown>)['platforms'] as unknown[]) ?? []).map(String)
+            : ['x'];
+          if (!platforms.includes('x')) {
+            throw new Error('marketing.post_all currently supports X-only on this controller.');
+          }
+
+          const nodeOutputsDir = path.join(runDir, 'node-outputs');
+          const draftsFromNode = String((toolArgs as Record<string, unknown>)?.['draftsFromNode'] ?? '').trim() || 'qc_brand';
+          let text = await loadProposedPostTextFromPriorNode({ runDir, nodeOutputsDir, priorNodeId: draftsFromNode });
+          if (!text?.trim()) throw new Error('marketing.post_all: missing draft text');
+
+          const dryRun = Boolean((toolArgs as Record<string, unknown>)?.['dryRun']);
+
+          // Never publish internal draft/instruction/disclaimer copy.
+          text = text
+            .split(/\r?\n/)
+            .filter((line) => !/draft\s*only/i.test(line))
+            .filter((line) => !/do\s+not\s+post\s+without\s+approval/i.test(line))
+            .filter((line) => !/clawrecipes\s+before\s+openclaw/i.test(line))
+            .filter((line) => !/nothing\s+posts\s+without\s+approval/i.test(line))
+            .join('\n')
+            .trim();
+
+          if (dryRun) {
+            const logRel = path.join('shared-context', 'marketing', 'POST_LOG.md');
+            const logAbs = path.join(teamDir, logRel);
+            await ensureDir(path.dirname(logAbs));
+            await fs.appendFile(
+              logAbs,
+              `- ${new Date().toISOString()} [DRY_RUN] run=${runId} node=${node.id} tool=${toolName} platforms=x\n  - text: ${JSON.stringify(text)}\n`,
+              'utf8',
+            );
+
+            const result = { dryRun: true, platformsWouldPost: ['x'], draftText: text, logPath: logRel };
+            await fs.writeFile(artifactPath, JSON.stringify({ ok: true, tool: toolName, args: toolArgs, result }, null, 2) + '\n', 'utf8');
+          } else {
+            const who = await execFileP('xurl', ['whoami'], { timeout: 60_000, env: { ...process.env, NO_COLOR: '1' } });
+            const whoJson = JSON.parse(String((who as { stdout?: string }).stdout ?? ''));
+            const username = String((whoJson as { data?: { username?: string } })?.data?.username ?? '').trim();
+            if (!username) throw new Error('marketing.post_all: could not resolve X username');
+
+            const postRes = await execFileP('xurl', ['post', text], { timeout: 60_000, env: { ...process.env, NO_COLOR: '1' } });
+            const postJson = JSON.parse(String((postRes as { stdout?: string }).stdout ?? ''));
+            const postId = String((postJson as { data?: { id?: string } })?.data?.id ?? '').trim();
+            if (!postId) throw new Error('marketing.post_all: xurl post did not return an id');
+
+            const url = `https://x.com/${username}/status/${postId}`;
+            const result = { platformsPosted: ['x'], x: { postId, url, username } };
+            await fs.writeFile(artifactPath, JSON.stringify({ ok: true, tool: toolName, args: toolArgs, result }, null, 2) + '\n', 'utf8');
+          }
         } else {
           const toolRes = await toolsInvoke<unknown>(api, {
             tool: toolName,