@crewx/workflow 0.3.22-rc.3 → 0.3.22-rc.30

package/SKILL.md

@@ -35,12 +35,20 @@ crewx workflow show standard-dev-core --mermaid
 # Validate all workflow files
 crewx workflow validate
 
-# Start a workflow execution
-crewx workflow run start standard-dev-core --set goal="implement feature X"
+# Start a workflow execution and auto-run until completion/pause
+crewx workflow run start standard-dev-core --set goal="implement feature X" --auto
+
+# In the CrewX web chat, start a workflow as a signed ChatCard.
+# Text after the workflow id becomes state.input.
+/wf rc-publish prepare the next RC
+/wf rc-publish --manual dry run only
 
 # Move to a node
 crewx workflow run node <exec-id> research
 
+# Resume auto-run from the current node
+crewx workflow run auto <exec-id>
+
 # Check execution state
 crewx workflow run state <exec-id>
 ```
@@ -78,10 +86,12 @@ crewx workflow validate workflows/standard-dev.yaml  # Validate a specific file
 ### `workflow run start <id|file>`
 
 Creates a new execution instance. State is stored as a JSON file in `.crewx/workflow-runs/`.
+Add `--auto` to immediately execute deterministic nodes and agent nodes until the run reaches `end`, `approval`, `parallel`, or a failure.
 
 ```bash
 crewx workflow run start standard-dev-core
 crewx workflow run start standard-dev-core --set goal="build auth module"
+crewx workflow run start standard-dev-core --set goal="build auth module" --auto
 crewx workflow run start workflows/idea-validation.yaml
 ```
 
@@ -109,6 +119,36 @@ crewx workflow run node wfr_abc12345 research
 crewx workflow run node wfr_abc12345 end
 ```
 
+### `workflow run auto <exec-id>`
+
+Auto-runs from the current node until the workflow reaches a natural pause or terminal state.
+
+```bash
+crewx workflow run auto wfr_abc12345
+crewx workflow run auto wfr_abc12345 --json
+```
+
+Auto mode executes these node types directly:
+
+| Node type | Auto behavior |
+|-----------|---------------|
+| `agent_task` | Invokes the configured agent via `crewx q/x`, stores output if `output` is set, then follows `next` |
+| `skill_task` | Runs `crewx skill <skill> ...args`, stores output if `output` is set, then follows `next` |
+| `shell_task` | Runs a gated argv command with `shell: false`, stores output if `output` is set, then follows `next` |
+| `expression` | Evaluates safe state expressions and follows `next` |
+| `branch` | Evaluates the branch condition and moves to the selected node |
+| `join` | Checks predecessor completion and follows `next` |
+| `end` | Marks the run as completed |
+
+Auto mode pauses instead of crossing these boundaries:
+
+| Node type | Why it pauses |
+|-----------|---------------|
+| `approval` | Requires an explicit human approve/reject decision |
+| `parallel` | Branch scheduling/convergence must be handled separately |
+
+`max_iterations` limits auto-run steps and prevents infinite loops.
+
 ### `workflow run reset <exec-id>`
 
 Restores execution state to `initial_state`.
@@ -181,6 +221,42 @@ analyze:
   next: calculate
 ```
 
+#### agent_task — execution context & failure signaling
+
+Every `agent_task` prompt is automatically prefixed with a `<crewx.workflow>` preamble
+telling the agent it runs headless inside a workflow node (workflow ID, node ID, run ID),
+that clarifying questions are impossible, and how to signal failure. Disable with
+`CREWX_WORKFLOW_PREAMBLE=off`.
+
+Two semantic-failure channels stop the run at the node (in addition to non-zero exit codes):
+
+1. **`workflow_signal` (agent-initiated)** — the agent outputs exactly one JSON object:
+
+   ```json
+   {"workflow_signal": "fail", "reason": "build is red — tsc reports 14 errors"}
+   ```
+
+   The engine detects it (pure JSON or embedded in prose), marks the node failed, and
+   records the reason in `run.error`. This is the agent's `exit 1`.
+
+2. **`fail_when` (node-declared)** — a safe expression evaluated against state *after*
+   the node's output is stored. Truthy → node fails, run halts. The judged output is
+   still preserved in state for inspection. No separate `check_*` branch node needed.
+
+   ```yaml
+   verify:
+     type: agent_task
+     agent: core_dev
+     output: verify_result
+     output_format: json
+     fail_when: 'state.verify_result.status !== "pass"'
+     next: smoke_test
+   ```
+
+   `fail_when` works on `agent_task`, `skill_task`, and `shell_task`. It uses the same
+   safe expression subset as `branch` conditions (`includes()`, `===`, `&&`, `Number()`...).
+   Use `branch` when failure should route somewhere; use `fail_when` when failure should stop the run.
+
 #### agent_task — JSON output mode
 
 When `output_format: json`, the engine requires the agent to return a single JSON object.
@@ -232,6 +308,81 @@ The schema is validated against JSON Schema 2020-12 (`@hyperjump/json-schema`).
 
 OpenAI Structured Outputs compatible — use `output_strict: true` to enforce the subset in the LLM prompt.
 
+### `skill_task` -- Run a CrewX skill
+
+Runs a built-in or registered CrewX skill without asking an agent to do the mechanical work. Use this for deterministic steps such as document extraction, search, indexing, validation, or other skill-backed commands.
+
+```yaml
+extract_attachments:
+  type: skill_task
+  skill: ocr-extractor
+  args: ["--input", "{{attachment_dir}}", "--json"]
+  output: extracted_text
+  output_format: json
+  output_retry: 2
+  timeout: 600
+  next: analyze
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `skill` | string | **Yes** | Skill name. Must match `^[a-z0-9][a-z0-9-]*$`; path traversal and special characters are rejected. |
+| `args` | string[] | No | CLI arguments appended after the skill name. Supports `{{state}}` template interpolation. |
+| `cwd` | string | No | Working directory. Normalized and constrained under the project root. |
+| `output` | string | No | State key to store stdout. |
+| `output_format` | `'json'` | No | Parse stdout as JSON and validate with `output_schema` if provided. |
+| `output_schema` | object | No | Standard JSON Schema 2020-12 for parsed output. |
+| `output_retry` | integer | No | Retry attempts if JSON parse or schema validation fails. |
+
+`skill_task` uses `CREWX_CLI` (default: `npx crewx`) and executes the equivalent of:
+
+```bash
+crewx skill <skill> ...args
+```
+
+### `shell_task` -- Run a gated argv command
+
+Runs a local command only when both safety gates are enabled:
+
+1. Environment opt-in: `CREWX_WORKFLOW_SHELL=1`
+2. Workflow opt-in: `metadata.shell_task_allowed: true`
+
+```yaml
+workflows:
+  build-check:
+    metadata:
+      name: "Build check"
+      shell_task_allowed: true
+    nodes:
+      build:
+        type: shell_task
+        command: ["pnpm", "run", "build"]
+        cwd: "."
+        output: build_log
+        timeout: 600
+        next: end
+      end:
+        type: end
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `command` | string[] | **Yes** | argv array. Plain string commands are rejected. `command[0]` is the program; remaining values are args. |
+| `cwd` | string | No | Working directory. Normalized and constrained under the project root. |
+| `env` | object | No | Explicit env pass-through. Dangerous keys such as `LD_PRELOAD` are rejected. |
+| `output` | string | No | State key to store stdout. |
+| `output_format` | `'json'` | No | Parse stdout as JSON and validate with `output_schema` if provided. |
+| `output_schema` | object | No | Standard JSON Schema 2020-12 for parsed output. |
+| `output_retry` | integer | No | Retry attempts if JSON parse or schema validation fails. |
+
+Security rules:
+
+- `shell_task.command` must be an argv array; it never runs through a shell.
+- Shell interpreters such as `sh`, `bash`, `zsh`, `fish`, `cmd`, and `powershell` are blocked.
+- Inline code flags such as `node -e`, `python -c`, and `ruby -e` are blocked.
+- Parent environment is not inherited wholesale; only a minimal allowlist plus explicit safe `env` keys is passed.
+- Commands run with timeout and process-group termination.
+
 ### `parallel` -- Fan-out to concurrent branches
 
 ```yaml
@@ -325,14 +476,15 @@ end:
 | `on_failure` | string | `fail_fast` \| `continue` \| `ignore` |
 | `on_error` | object | `{ handler?, fallback_node? }` |
 | `comment` | string | Human-readable annotation |
-| `output_format` | `'json'` | Enable JSON output mode (`agent_task` only) |
+| `output` | string | State key to store stdout/result (`agent_task`, `skill_task`, `shell_task`) |
+| `output_format` | `'json'` | Enable JSON output mode (`agent_task`, `skill_task`, `shell_task`) |
 | `output_schema` | object | Standard JSON Schema 2020-12 for output validation |
 | `output_strict` | boolean | Apply OpenAI Structured Outputs subset to LLM prompt (default: `false`) |
 | `output_retry` | integer | Retry count if JSON parse/validation fails (default: `1`) |
 
 ## Template Syntax
 
-Use `{{variable_name}}` in `input` fields to reference `state` values.
+Use `{{variable_name}}` in fields such as `input`, `args`, `command`, `cwd`, and `env` values to reference `state` values.
 
 ```yaml
 state:
@@ -383,6 +535,9 @@ const exec: RunExecution = manager.start('workflows/dev.yaml', 'dev-core', { goa
 // Execute a node (triggers agent call for agent_task nodes)
 const updated: RunExecution = await manager.executeNode(exec.id, 'research');
 
+// Auto-run until end, approval, parallel, or failure
+const autoResult = await manager.runAuto(exec.id);
+
 // Move to node without executing
 const moved: RunExecution = manager.moveNode(exec.id, 'implement');
 ```
@@ -390,7 +545,16 @@ const moved: RunExecution = manager.moveNode(exec.id, 'implement');
 ### Key Types
 
 ```typescript
-type NodeType = 'agent_task' | 'parallel' | 'join' | 'branch' | 'approval' | 'expression' | 'end';
+type NodeType =
+  | 'agent_task'
+  | 'skill_task'
+  | 'shell_task'
+  | 'parallel'
+  | 'join'
+  | 'branch'
+  | 'approval'
+  | 'expression'
+  | 'end';
 
 interface RunExecution {
   id: string;                          // 'wfr_{nanoid(8)}'
@@ -402,10 +566,82 @@ interface RunExecution {
   completed_nodes: string[];
   state: Record<string, unknown>;
   initial_state: Record<string, unknown>;
+  audit?: Array<{
+    node_id: string;
+    type: NodeType;
+    status: 'success' | 'failed' | 'timeout';
+    started_at: string;
+    finished_at: string;
+    duration_ms: number;
+    exit_code?: number | null;
+    trigger?: 'manual' | 'auto';
+  }>;
   status?: 'running' | 'completed' | 'failed';
 }
 ```
 
+## Web UI `/wf` ChatCard Integration
+
+The CrewX web chat treats workflow runs as **conversation content**, not as a side panel. When a user sends a `/wf` command, the server creates a workflow run, stores the original user message in the thread transcript, and stores an assistant message containing a signed workflow ChatCard.
+
+### Syntax
+
+```text
+/wf <workflow-id> [input...]
+/wf <workflow-id> --manual [input...]
+/wf <workflow-id> --auto [input...]
+```
+
+Examples:
+
+| Input | Run behavior |
+|-------|--------------|
+| `/wf rc-publish` | Starts `rc-publish` in auto mode |
+| `/wf rc-publish 미리승인한다` | Starts `rc-publish` with `state.input = "미리승인한다"` |
+| `/wf rc-publish --manual dry run` | Creates the run in manual mode with `state.input = "dry run"` |
+| `/wf rc-publish --auto prepare RC notes` | Explicit auto mode; same as default |
+
+`--manual` and `--auto` are parsed as options and are **not** included in `state.input`. All remaining text after the workflow id is copied to `state.input`.
+
+### `state.input`
+
+`state.input` is the standard entry point for user instructions passed into a workflow run.
+
+```yaml
+nodes:
+  - id: plan
+    type: agent_task
+    agent: "@core_dev"
+    prompt: |
+      User instruction:
+      {{input}}
+
+      Plan and execute the workflow step accordingly.
+```
+
+Branches and templates may also read `state.input`:
+
+```yaml
+condition: state.input.includes("dry run")
+```
+
+Important security rule: `state.input` is **not authority**. It may influence prompts, branches, and templates, but it must never bypass an `approval` node. For example, `/wf rc-publish 미리승인한다` stores the text in `state.input`; it does not approve publishing. Approval still requires the signed ChatCard action button.
+
+### Stored ChatCard
+
+The assistant message stores only a signed reference to the workflow run:
+
+```xml
+<crewx_card type="workflow" version="1" run_id="wfr_xxx" workflow_id="rc-publish" mode="auto" proof="jwt..." />
+```
+
+Rules:
+
+- The `proof` is server-issued and expires after 7 days.
+- Raw `<crewx_card>` text from users is rendered as plain text.
+- Workflow actions such as resolve, auto resume, approve, reject, and cancel require a valid proof bound to the current workspace/thread/task.
+- The mutable run state remains in `.crewx/workflow-runs/`; the ChatCard stores only a reference.
+
 ## Architecture
 
 ```
@@ -417,29 +653,37 @@ interface RunExecution {
          v
     workflows/*.yaml  (source files)
 
-[CLI]  crewx workflow run start/node/state
+[CLI]  crewx workflow run start/node/state/auto
          |
          v
     RunManager  <-- execution state management
          |
          +---> .crewx/workflow-runs/wfr_*.json  (state files)
-         +---> crewx q/x  (agent invocation for agent_task nodes)
+         +---> crewx q/x                 (agent_task)
+         +---> crewx skill <skill>       (skill_task)
+         +---> argv command, shell:false (shell_task; gated)
 
 [Server]  GET /api/v1/workflows[/:id]
+          POST /api/v1/workflows/:id/runs
+          GET/POST /api/v1/workflows/runs/:execId/*
          |
          v
-    WorkflowService  --> fs (YAML read) + WorkflowEngine.toMermaid()
+    WorkflowService  --> fs (YAML read) + WorkflowEngine + RunManager
+          |
+          +---> Thread transcript card:
+                <crewx_card type="workflow" run_id="..." workflow_id="..." mode="auto" proof="jwt..." />
 ```
 
-> **Note:** The server only uses `WorkflowEngine.toMermaid()`. YAML listing/parsing is handled by the server's own `WorkflowService`. `RunManager` (execution state) is CLI-only.
+> **Note:** The server uses `RunManager` for workflow runs and stores workflow UI references as ChatCard tags in thread messages. The mutable run status/state remains in `.crewx/workflow-runs/` and is fetched by `run_id`.
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CREWX_WORKSPACE` | Workspace directory (where `workflows/` lives) | `.` |
-| `CREWX_CLI` | CrewX CLI path (for agent execution in `run node`) | `npx crewx` |
-| `CREWX_WORKFLOW_TIMEOUT` | Node execution timeout (ms) | `1800000` (30 min) |
+| `CREWX_CLI` | CrewX CLI path (for `agent_task` and `skill_task`) | `npx crewx` |
+| `CREWX_WORKFLOW_TIMEOUT` | `agent_task` execution timeout (ms) | `1800000` (30 min) |
+| `CREWX_WORKFLOW_SHELL` | First safety gate for `shell_task`; must be `1` | unset |
 | `CREWX_CONFIG` | Custom config file path | `crewx.yaml` |
 
 ## WARNING: Check Agent List Before Designing

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAgB,YAAY,EAAgB,MAAM,aAAa,CAAC;AA6F5F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;CACrC;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,CAAC,EAAE,cAAc,EAAE,GAC3B,gBAAgB,CAkDlB;AA6sBD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAClC,MAAM,GAAG,IAAI,CAkBf;AAMD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,EAAE,CAsB1E;AA4CD,wBAAsB,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD9D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAgB,YAAY,EAA+B,MAAM,aAAa,CAAC;AA6F3G,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;CACrC;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,CAAC,EAAE,cAAc,EAAE,GAC3B,gBAAgB,CAkDlB;AAmxBD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAClC,MAAM,GAAG,IAAI,CAoBf;AAMD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,EAAE,CAsB1E;AA4CD,wBAAsB,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD9D"}

package/dist/cli.js

@@ -63,7 +63,7 @@ async function loadTracer() {
         return null;
     }
 }
-const BOOLEAN_FLAGS = new Set(['help', 'json', 'mermaid', 'version', 'no-exec']);
+const BOOLEAN_FLAGS = new Set(['help', 'json', 'mermaid', 'version', 'no-exec', 'auto']);
 function parseArgs(args) {
     const result = { positional: [], options: {} };
     for (let i = 0; i < args.length; i++) {
@@ -193,10 +193,11 @@ Commands:
   workflow list                    List all workflows
   workflow show <id|file>          Show workflow detail
   workflow validate [id|file]      Validate workflow YAML
-  workflow run start <id|file>     Create new execution
+  workflow run start <id|file>     Create new execution (add --auto to run to completion)
   # Resolution: .yaml path → workflow ID → filename slug
   workflow run state <id>          Get/set execution state
   workflow run node <id> <node>    Execute node (auto-invoke agent)
+  workflow run auto <id>           Auto-run from current node until end/pause
   workflow run reset <id>          Reset execution
   workflow run list                List all executions
   workflow usage                   Show detailed guide
@@ -298,8 +299,8 @@ function cmdList(engine, jsonMode) {
         const firstId = workflows[0]?.id;
         if (firstId) {
             console.log(`\n${'━'.repeat(43)}`);
-            console.log(`🔍 워크플로 상세:  npx workflow show ${firstId}`);
-            console.log(`🔀 워크플로 실행:  npx workflow run start <id> --set key="value"`);
+            console.log(`🔍 Workflow details:  npx workflow show ${firstId}`);
+            console.log(`🔀 Run workflow:  npx workflow run start <id> --set key="value"`);
         }
         const listCtx = {
             commandId: 'workflow.list',
@@ -564,8 +565,18 @@ async function cmdRun(rest, rawArgs, jsonMode, engine) {
                 process.exit(1);
             }
             const sets = (0, run_manager_1.parseSetArgs)(rawArgs);
+            const auto = rawArgs.includes('--auto');
             try {
                 const run = mgr.start(resolved.filePath, resolved.workflowId ?? positional[1], Object.keys(sets).length > 0 ? sets : undefined);
+                if (auto) {
+                    if (!jsonMode) {
+                        console.log(`✅ Created execution: ${run.id}`);
+                        console.log(`   Workflow: ${run.workflow_id} (${resolved.filePath})`);
+                    }
+                    const result = await mgr.runAuto(run.id);
+                    reportAutoResult(result, jsonMode);
+                    break;
+                }
                 if (jsonMode) {
                     console.log(JSON.stringify({ success: true, exec_id: run.id, run }, null, 2));
                 }
@@ -828,8 +839,39 @@ async function cmdRun(rest, rawArgs, jsonMode, engine) {
             }
             break;
         }
+        case 'auto': {
+            const positional = runArgs.filter(a => !a.startsWith('--'));
+            const execId = positional[0];
+            if (!execId) {
+                const msg = 'Usage: workflow run auto <exec-id>';
+                if (jsonMode) {
+                    console.log(JSON.stringify({ success: false, error: msg }));
+                }
+                else {
+                    console.error(`❌ ${msg}`);
+                }
+                process.exit(1);
+            }
+            try {
+                const result = await mgr.runAuto(execId);
+                reportAutoResult(result, jsonMode);
+                if (result.outcome === 'failed')
+                    process.exit(1);
+            }
+            catch (e) {
+                const msg = e.message;
+                if (jsonMode) {
+                    console.log(JSON.stringify({ success: false, error: msg }));
+                }
+                else {
+                    console.error(`❌ ${msg}`);
+                }
+                process.exit(1);
+            }
+            break;
+        }
         default: {
-            const msg = `Unknown run subcommand: ${runSub || '(none)'}\nUsage: workflow run <start|state|node|reset|list> [args...]`;
+            const msg = `Unknown run subcommand: ${runSub || '(none)'}\nUsage: workflow run <start|state|node|auto|reset|list> [args...]`;
             if (jsonMode) {
                 console.log(JSON.stringify({ success: false, error: msg }));
             }
@@ -840,12 +882,39 @@ async function cmdRun(rest, rawArgs, jsonMode, engine) {
         }
     }
 }
+function reportAutoResult(result, jsonMode) {
+    const { run, outcome, reason, executed } = result;
+    const status = run.status ?? (outcome === 'paused' ? 'paused' : 'running');
+    if (jsonMode) {
+        console.log(JSON.stringify({
+            success: outcome !== 'failed',
+            exec_id: run.id,
+            status,
+            outcome,
+            current_node: run.current_node,
+            completed_nodes: run.completed_nodes,
+            executed,
+            ...(reason ? { reason } : {}),
+        }, null, 2));
+        return;
+    }
+    const icon = outcome === 'failed' ? '❌' : outcome === 'paused' ? '⏸️' : '✅';
+    console.log(`${icon} Auto run: ${run.id}`);
+    if (executed.length > 0) {
+        console.log(`   Executed: ${executed.join(' → ')}`);
+    }
+    console.log(`   Outcome: ${outcome}${reason ? ` (${reason})` : ''}`);
+    console.log(`   Current: ${run.current_node || '(none)'}`);
+    console.log(`   Status: ${status}`);
+}
 function findNextNodeForCAL(currentNode, executedNodeId, nodes) {
     const executedNode = nodes[executedNodeId];
     if (!executedNode)
         return null;
     switch (executedNode.type) {
         case 'agent_task':
+        case 'skill_task':
+        case 'shell_task':
         case 'expression':
             return typeof executedNode.next === 'string' ? executedNode.next : null;
         case 'branch':