feat: Introduce agent-native execution contract and resilience features

- Added structured output for machine-readable execution results in JSON and JSONL formats.
- Implemented stable exit codes for various failure scenarios including parse, SSH config, runtime, and timeout failures.
- Introduced resilience controls with timeout and retry directives for block execution.
- Enabled named exports to propagate environment variables between blocks.
- Added safety controls including no-input mode and dry-run functionality.
- Created comprehensive BDD scenarios to validate new features and ensure backward compatibility.
- Developed detailed design documentation outlining the architecture and implementation plan.

Author: Akagi201

.gitignore

@@ -41,3 +41,5 @@ Thumbs.db
 .env
 .env.local
 .rumdl_cache/
+.benchmarks/
+.hypothesis/

README.md

@@ -1,5 +1,7 @@
 # ShellFlow
 
+> AI agent native DevOps bash script orchestrator.
+
 [![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/longcipher/shellflow)
 [![Context7](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com/longcipher/shellflow)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
@@ -18,6 +20,10 @@ ShellFlow is a minimal shell script orchestrator for mixed local and remote exec
 - Run each block fail-fast, in order.
 - Reuse the shared prelude before the first marker for every block.
 - Pass the previous block output forward as `SHELLFLOW_LAST_OUTPUT`.
+- Export named scalar values from a block into later block environments.
+- Emit either a final JSON report or streaming JSON Lines events for agents.
+- Support bounded `@TIMEOUT` and `@RETRY` directives without embedding workflow logic.
+- Provide non-interactive, dry-run, and audit-log modes for automated execution.
 - Resolve remote targets from `~/.ssh/config` or a custom SSH config path.
 
 ## Quick Start
@@ -80,6 +86,12 @@ Shellflow recognizes two markers:
 - `# @LOCAL`
 - `# @REMOTE <ssh-host>`
 
+Shellflow also recognizes bounded block directives at the top of a block body:
+
+- `# @TIMEOUT <seconds>`
+- `# @RETRY <count>`
+- `# @EXPORT NAME=stdout|stderr|output|exit_code`
+
 `<ssh-host>` must match a `Host` entry in your SSH config. Shellflow then connects using that SSH host definition, which means the actual machine can be resolved through the configured `HostName`, `User`, `Port`, and `IdentityFile` values.
 
 Example:
@@ -89,13 +101,15 @@ Example:
 set -euo pipefail
 
 # @LOCAL
+# @EXPORT VERSION=stdout
 echo "runs locally"
 
 # @REMOTE sui
 uname -a
 
 # @LOCAL
 echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+echo "version = $VERSION"
 ```
 
 ## SSH Configuration
@@ -141,6 +155,18 @@ echo "build-123"
 echo "last output = $SHELLFLOW_LAST_OUTPUT"
 ```
 
+Named exports are additive to `SHELLFLOW_LAST_OUTPUT`:
+
+```bash
+# @LOCAL
+# @EXPORT VERSION=stdout
+echo "2026.03.15"
+
+# @REMOTE sui
+echo "deploying $VERSION"
+echo "last output = $SHELLFLOW_LAST_OUTPUT"
+```
+
 Lines before the first marker are treated as a shared prelude and prepended to every executable block:
 
 ```bash
@@ -154,11 +180,41 @@ echo "prelude is active"
 echo "prelude is also active here"
 ```
 
+## Agent-Native Usage
+
+Shellflow is designed to be the execution substrate for an outer agent, not an embedded planner.
+
+- Use `--json` when you want one final machine-readable run report.
+- Use `--jsonl` when you want ordered event records while the script runs.
+- Use `--no-input` for CI or agent runs where interactive prompts must fail deterministically.
+- Use `--dry-run` to preview planned execution without running commands.
+- Use `--audit-log <path>` to mirror the structured event stream into a redacted JSONL file.
+
+Recommended agent flow:
+
+1. Generate or select a plain shell script with `@LOCAL` and `@REMOTE` markers.
+2. Add bounded directives only where needed: `@TIMEOUT`, `@RETRY`, and `@EXPORT`.
+3. Run with `--json` or `--jsonl`.
+4. Let the outer agent decide whether to retry, branch, or stop based on Shellflow's structured result.
+
+Shellflow intentionally does not provide:
+
+- Conditional directives such as `@IF stdout_contains=...`
+- A workflow DSL or embedded ReAct loop
+- Heuristic destructive-command detection
+
+Those decisions belong in the outer agent or automation layer.
+
 ## CLI
 
 ```text
 shellflow run <script>
 shellflow run <script> --verbose
+shellflow run <script> --json
+shellflow run <script> --jsonl
+shellflow run <script> --no-input
+shellflow run <script> --dry-run
+shellflow run <script> --audit-log ./audit.jsonl --jsonl
 shellflow run <script> --ssh-config ./ssh_config
 shellflow --version
 ```
@@ -168,6 +224,10 @@ Examples:
 ```bash
 shellflow run playbooks/hello.sh
 shellflow run playbooks/hello.sh -v
+shellflow run playbooks/hello.sh --json
+shellflow run playbooks/hello.sh --jsonl --no-input
+shellflow run playbooks/hello.sh --dry-run --jsonl
+shellflow run playbooks/hello.sh --audit-log ./audit.jsonl --jsonl
 shellflow run playbooks/hello.sh --ssh-config ~/.ssh/config.work
 ```
 

features/execution_contract.feature

@@ -0,0 +1,29 @@
+Feature: Agent-facing execution contract
+  As an AI agent operating Shellflow
+  I want structured execution results and stable exit codes
+  So that I can observe outcomes and decide what to do next outside Shellflow
+
+  Scenario: JSON report mode returns machine-readable run and block results
+    Given a script file with a local block that prints a release version
+    When I run the script with JSON output enabled
+    Then the command should succeed
+    And the JSON output should contain a run id
+    And the JSON output should contain a schema version
+    And the JSON output should include the first block exit code
+    And the JSON output should include the first block stdout separately from stderr
+
+  Scenario: JSONL mode emits ordered events suitable for live observation
+    Given a script file with two local blocks that both succeed
+    When I run the script with JSON Lines output enabled
+    Then the command should succeed
+    And the output should contain a run_started event before a block_started event
+    And the output should contain a block_finished event for each block
+    And the output should end with a run_finished event
+
+  Scenario: Exit codes distinguish parse, SSH config, runtime, and timeout failures
+    Given the relevant failing scripts for parse, missing SSH host, block failure, and timeout
+    When I run each script in machine-readable mode
+    Then the parse failure should exit with code 2
+    And the missing SSH host failure should exit with code 3
+    And the block execution failure should exit with code 1
+    And the timeout failure should exit with code 4

features/resilience_and_context.feature

@@ -0,0 +1,24 @@
+Feature: Resilience and context propagation
+  As an AI agent using Shellflow as an action tool
+  I want bounded retries, timeouts, and named exports
+  So that I can recover from transient failures without turning Shellflow into a workflow engine
+
+  Scenario: Timeout stops a stuck block and reports a timeout-specific failure
+    Given a script file with a local block that exceeds its timeout directive
+    When I run the script in machine-readable mode
+    Then the command should fail with timeout exit code 4
+    And the structured output should mark the block as timed out
+    And the structured output should record the timeout duration policy
+
+  Scenario: Retry reruns a transiently failing block and reports attempts
+    Given a script file with a local block that fails once and then succeeds with a retry directive
+    When I run the script in machine-readable mode
+    Then the command should succeed
+    And the structured output should record 2 attempts for that block
+    And the structured output should include a retrying event before the successful finish event
+
+  Scenario: Named exports become environment variables for later blocks
+    Given a script file whose first block exports VERSION from stdout
+    When I run the script
+    Then the later block should receive VERSION in its environment
+    And SHELLFLOW_LAST_OUTPUT should still be available

features/safety_controls.feature

@@ -0,0 +1,24 @@
+Feature: Safety controls for automated runs
+  As an operator delegating execution to an AI agent
+  I want non-interactive and audit-friendly controls
+  So that automated runs are observable without relying on shell heuristics
+
+  Scenario: No-input prevents blocking on stdin
+    Given a script file with a local block that reads from standard input
+    When I run the script with no-input enabled
+    Then the command should fail deterministically instead of waiting for input
+    And the structured output should indicate that no interactive input was available
+
+  Scenario: Dry-run previews execution without running commands
+    Given a script file with local and remote blocks
+    When I run the script in dry-run mode
+    Then no block commands should be executed
+    And the output should describe the planned blocks in order
+    And the output should include structured dry-run events when machine-readable mode is enabled
+
+  Scenario: Audit-log writes structured events for later inspection
+    Given a script file with a named export that looks like a secret
+    When I run the script with an audit log path
+    Then the command should succeed
+    And the audit log file should contain JSON Lines events
+    And the audit log should redact the secret-like exported value