feat: add experimental acpx flows runtime and examples

CHANGELOG.md

@@ -8,6 +8,8 @@ Repo: https://github.com/openclaw/acpx
 
 - Conformance/ACP: add a data-driven ACP core v1 conformance suite with CI smoke coverage, nightly coverage, and a hardened runner that reports startup failures cleanly and scopes filesystem checks to the session cwd. (#130) Thanks @lynnzc.
 - Agents/droid: add `factory-droid` and `factorydroid` aliases for the built-in Factory Droid adapter and sync the built-in docs. Thanks @vincentkoc.
+- Flows/workflows: add an initial `flow run` command, an `acpx/flows` runtime surface, and file-backed flow run state under `~/.acpx/flows/runs` for user-authored workflow modules. Thanks @osolmaz.
+- Flows/workspaces: let `acp` nodes bind to an explicit per-step cwd, add a native isolated-workspace example, and default active flow steps to a 15 minute timeout unless overridden. Thanks @osolmaz.
 
 ### Breaking
 

README.md

@@ -39,6 +39,9 @@ One command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatibl
 - **Structured output**: typed ACP messages (thinking, tool calls, diffs) instead of ANSI scraping
 - **Any ACP agent**: built-in registry + `--agent` escape hatch for custom servers
 - **One-shot mode**: `exec` for stateless fire-and-forget tasks
+- **Experimental flows**: `flow run <file>` for TypeScript workflow modules over multiple prompts
+- **Runtime-owned flow actions**: shell-backed action steps can prepare workspaces and other deterministic mechanics outside the agent turn
+- **Flow workspace isolation**: `acp` nodes can target an explicit per-step cwd, so flows can keep agent work inside disposable worktrees
 
 ```bash
 $ acpx codex sessions new
@@ -204,13 +207,47 @@ acpx --cwd ~/repos/backend codex 'review recent auth changes'
 acpx --format text codex 'summarize your findings'
 acpx --format json codex exec 'review changed files'
 acpx --format json --json-strict codex exec 'machine-safe JSON only'
+acpx flow run ./my-flow.ts --input-file ./flow-input.json
+acpx --timeout 1800 flow run ./my-flow.ts
 acpx --format quiet codex 'final recommendation only'
 
 acpx --timeout 90 codex 'investigate intermittent test timeout'
 acpx --ttl 30 codex 'keep queue owner alive for quick follow-ups'
 acpx --verbose codex 'debug why adapter startup is failing'
 ```
 
+## Flows
+
+`acpx flow run <file>` executes a TypeScript flow module through the `acpx/flows`
+runtime and persists run state under `~/.acpx/flows/runs/`.
+
+Flows are for multi-step ACP work where one prompt is not enough:
+
+- `acp` steps keep model-shaped work in ACP
+- `action` steps handle deterministic mechanics like shell commands or GitHub calls
+- `compute` steps do local routing or shaping
+- `checkpoint` steps pause for something outside the runtime
+
+The source tree includes flow examples under [examples/flows/README.md](examples/flows/README.md):
+
+- small examples such as `echo`, `branch`, `shell`, `workdir`, and `two-turn`
+- a larger PR-triage example under [examples/flows/pr-triage/README.md](examples/flows/pr-triage/README.md)
+
+Example runs:
+
+```bash
+acpx flow run ./my-flow.ts --input-file ./flow-input.json
+
+acpx flow run examples/flows/branch.flow.ts \
+  --input-json '{"task":"FIX: add a regression test for the reconnect bug"}'
+
+acpx flow run examples/flows/pr-triage/pr-triage.flow.ts \
+  --input-json '{"repo":"openclaw/acpx","prNumber":150}'
+```
+
+The PR-triage example is only an example workflow. It can comment on or close
+real GitHub PRs if you run it against a live repository.
+
 ## Configuration files
 
 `acpx` reads config in this order (later wins):