flowproof 0.2.0__tar.gz → 0.2.1__tar.gz

{flowproof-0.2.0 → flowproof-0.2.1}/Cargo.lock

@@ -722,7 +722,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-adapters"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "anyhow",
  "flowproof-driver",
@@ -738,7 +738,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-agent"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "chrono",
  "flowproof-driver",
@@ -753,7 +753,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-cli"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "ab_glyph",
  "clap",
@@ -765,12 +765,13 @@ dependencies = [
  "image",
  "imageproc",
  "serde_json",
+ "serde_yaml",
  "tiny_http",
 ]
 
 [[package]]
 name = "flowproof-driver"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "image",
  "postgres",
@@ -784,7 +785,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-python"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "flowproof-agent",
  "flowproof-cli",
@@ -796,7 +797,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-replay"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "chrono",
  "flowproof-agent",
@@ -809,7 +810,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-trace"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "jsonschema",
  "serde",

{flowproof-0.2.0 → flowproof-0.2.1}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/flowproof-driver", "crates/flowproof-trace", "crates/flowproof-replay", "crates/flowproof-agent", "crates/flowproof-adapters", "crates/flowproof-cli", "crates/flowproof-python"]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/automators-com/flowproof"

flowproof-0.2.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: flowproof
+Version: 0.2.1
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: mcp>=1.2 ; python_full_version >= '3.10' and extra == 'mcp'
+Provides-Extra: mcp
+Summary: Generic open-source automation framework for the AI-agent era: automated testing and agentic process automation across web, desktop, and Citrix.
+Author-email: Automators <hello@automators.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/automators-com/flowproof
+Project-URL: Repository, https://github.com/automators-com/flowproof
+
+# flowproof
+
+A generic open-source automation framework for the AI-agent era:
+automated testing and agentic process automation across web, desktop,
+and Citrix.
+
+**Agents author, a deterministic engine executes.** A flow is described in
+YAML with natural-language steps, recorded once against the live app, and
+replayed deterministically in CI with zero LLM calls. Built agent-native:
+every operation returns structured results a program can reason over, and
+agents can drive record/run/get_trace/heal over MCP
+(`pip install flowproof[mcp]`, run `flowproof-mcp`).
+
+```yaml
+# calc.flow.yaml
+name: Add two numbers
+app: calc
+steps:
+  - Type 5
+  - Press plus
+  - Type 3
+  - Press equals
+  - assert: display shows 8
+```
+
+```python
+from flowproof import Flow
+
+flow = Flow("calc.flow.yaml")
+flow.record()            # performs the flow live, writes the trace
+result = flow.run()      # deterministic replay -> RunResult
+assert result.passed
+```
+
+Or from the shell: `flowproof record calc.flow.yaml`, then
+`flowproof run calc.flow.yaml` (add `--json` for the structured report).
+
+The wheel bundles the Rust engine; no separate install. Targets: `web`
+(headless Chromium, any OS), Windows desktop via UI Automation, `sap`
+(SAP GUI Scripting), `vision` (pixels-only for Citrix/RDP), and `api`
+(no UI — HTTP/SQL assertion flows, any OS).
+
+**Status: early, in active development (v0.2).** Record→replay,
+model-grounded authoring, healing with reviewable diffs, suites, run
+recordings, and the MCP server all work and are tested in CI.
+
+Docs and source: [github.com/automators-com/flowproof](https://github.com/automators-com/flowproof)
+

flowproof-0.2.1/README.md

@@ -0,0 +1,47 @@
+# flowproof
+
+A generic open-source automation framework for the AI-agent era:
+automated testing and agentic process automation across web, desktop,
+and Citrix.
+
+**Agents author, a deterministic engine executes.** A flow is described in
+YAML with natural-language steps, recorded once against the live app, and
+replayed deterministically in CI with zero LLM calls. Built agent-native:
+every operation returns structured results a program can reason over, and
+agents can drive record/run/get_trace/heal over MCP
+(`pip install flowproof[mcp]`, run `flowproof-mcp`).
+
+```yaml
+# calc.flow.yaml
+name: Add two numbers
+app: calc
+steps:
+  - Type 5
+  - Press plus
+  - Type 3
+  - Press equals
+  - assert: display shows 8
+```
+
+```python
+from flowproof import Flow
+
+flow = Flow("calc.flow.yaml")
+flow.record()            # performs the flow live, writes the trace
+result = flow.run()      # deterministic replay -> RunResult
+assert result.passed
+```
+
+Or from the shell: `flowproof record calc.flow.yaml`, then
+`flowproof run calc.flow.yaml` (add `--json` for the structured report).
+
+The wheel bundles the Rust engine; no separate install. Targets: `web`
+(headless Chromium, any OS), Windows desktop via UI Automation, `sap`
+(SAP GUI Scripting), `vision` (pixels-only for Citrix/RDP), and `api`
+(no UI — HTTP/SQL assertion flows, any OS).
+
+**Status: early, in active development (v0.2).** Record→replay,
+model-grounded authoring, healing with reviewable diffs, suites, run
+recordings, and the MCP server all work and are tested in CI.
+
+Docs and source: [github.com/automators-com/flowproof](https://github.com/automators-com/flowproof)

flowproof-0.2.1/crates/flowproof-agent/src/clarify.rs

@@ -0,0 +1,177 @@
+//! Structured "this step could not be authored" payloads.
+//!
+//! flowproof deliberately has no in-loop clarification: when neither the
+//! rules nor the model can turn a step into a grounded action, recording
+//! stops and the *driving* agent (a human, or an MCP caller like DataMaker's
+//! agent) resolves the ambiguity — by consulting an external source of
+//! truth, rewriting the vague step into concrete grammar, and re-recording.
+//! This module is the machine-readable half of that loop: everything the
+//! driving agent needs to know *what* was ambiguous and *what the live
+//! screen offered* at the moment authoring gave up.
+
+use serde::{Deserialize, Serialize};
+
+/// Where authoring gave up on the step.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ClarifyStage {
+    /// The rules couldn't parse the step and no model backend is
+    /// configured — the payload carries the rules diagnostic.
+    NoModel,
+    /// The model was consulted (with one self-correcting retry) and still
+    /// couldn't ground the step to a listed element.
+    Model,
+}
+
+impl std::fmt::Display for ClarifyStage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            ClarifyStage::NoModel => "no model backend",
+            ClarifyStage::Model => "model could not ground",
+        })
+    }
+}
+
+/// One interactable element from the live scene at the moment of failure —
+/// the same grounding set the author saw, in structured form so the driving
+/// agent can enumerate fields ("which of these should the vague step
+/// change?") instead of re-scraping the app.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SceneElement {
+    /// Neutral target token (`css:…`, `id:…`, `text:…`) — usable verbatim
+    /// as a quoted target in a rewritten step.
+    pub target: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tag: Option<String>,
+    /// Associated label / aria-label / placeholder, when the driver saw one.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    /// Input type (`text`, `password`, …), when applicable.
+    #[serde(default, rename = "type", skip_serializing_if = "Option::is_none")]
+    pub input_type: Option<String>,
+}
+
+/// The full clarification payload. Text fields keep `${VAR}` references
+/// raw — nothing here ever holds a resolved secret.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Clarification {
+    /// The spec step that could not be authored, verbatim.
+    pub step: String,
+    /// 0-based index of that step in the spec.
+    pub step_index: usize,
+    pub stage: ClarifyStage,
+    /// Human-readable diagnostic from the stage that gave up.
+    pub reason: String,
+    /// The rules diagnostic, when the model stage was reached (the rules
+    /// failed first — their error often names the accepted forms).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub rules_error: Option<String>,
+    /// Intents already performed, in order — the app is left in the state
+    /// AFTER these, which is the state `scene` describes.
+    pub completed_steps: Vec<String>,
+    /// Interactable inventory of the live screen (may be empty when the
+    /// driver has no scene support).
+    pub scene: Vec<SceneElement>,
+    /// What to do next, for agents that don't know the loop.
+    pub hint: String,
+}
+
+impl Clarification {
+    pub const HINT: &'static str = "Rewrite the step using the grammar in docs/authoring.md, \
+         targeting a listed element (quote its label, or use its target token verbatim), \
+         then re-record. Consult your data source for domain questions the scene cannot \
+         answer (e.g. which fields are required).";
+}
+
+/// Parse a driver scene JSON into the structured inventory. Mirrors the
+/// author's grounding rules (`author.rs::scene_targets`): a modern element
+/// carries a `target` token; a legacy web element with only a `css` key is
+/// lifted to `css:<sel>`. Anything unparseable yields an empty inventory —
+/// a clarification without a scene is still useful.
+pub fn scene_inventory(scene: &str) -> Vec<SceneElement> {
+    serde_json::from_str::<Vec<serde_json::Value>>(scene)
+        .unwrap_or_default()
+        .iter()
+        .filter_map(|e| {
+            let target = e["target"]
+                .as_str()
+                .map(str::to_string)
+                .or_else(|| e["css"].as_str().map(|css| format!("css:{css}")))?;
+            let field = |key: &str| e[key].as_str().map(str::to_string);
+            Some(SceneElement {
+                target,
+                tag: field("tag"),
+                label: field("label"),
+                text: field("text"),
+                input_type: field("type"),
+            })
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_a_web_shaped_scene() {
+        let scene = r##"[
+            {"target": "css:#price", "css": "#price", "tag": "input",
+             "type": "text", "label": "Net Price"},
+            {"target": "text:Save", "tag": "button", "text": "Save"}
+        ]"##;
+        let inv = scene_inventory(scene);
+        assert_eq!(inv.len(), 2);
+        assert_eq!(inv[0].target, "css:#price");
+        assert_eq!(inv[0].label.as_deref(), Some("Net Price"));
+        assert_eq!(inv[0].input_type.as_deref(), Some("text"));
+        assert_eq!(inv[1].target, "text:Save");
+        assert_eq!(inv[1].text.as_deref(), Some("Save"));
+        assert!(inv[1].label.is_none());
+    }
+
+    #[test]
+    fn lifts_legacy_bare_css_entries() {
+        let inv = scene_inventory(r##"[{"css": "#total", "tag": "span"}]"##);
+        assert_eq!(inv.len(), 1);
+        assert_eq!(inv[0].target, "css:#total");
+    }
+
+    #[test]
+    fn garbage_scene_yields_empty_inventory() {
+        assert!(scene_inventory("not json").is_empty());
+        assert!(scene_inventory("[{\"no_target\": 1}]").is_empty());
+    }
+
+    #[test]
+    fn payload_serializes_to_the_documented_field_names() {
+        let c = Clarification {
+            step: "make required field changes".into(),
+            step_index: 4,
+            stage: ClarifyStage::Model,
+            reason: "target 'invented' is not one of the listed elements".into(),
+            rules_error: Some("no rule matches".into()),
+            completed_steps: vec!["Press the \"Edit\" button".into()],
+            scene: vec![SceneElement {
+                target: "css:#price".into(),
+                tag: Some("input".into()),
+                label: Some("Net Price".into()),
+                text: None,
+                input_type: Some("text".into()),
+            }],
+            hint: Clarification::HINT.into(),
+        };
+        let v = serde_json::to_value(&c).expect("serializes");
+        assert_eq!(v["stage"], "model");
+        assert_eq!(v["step_index"], 4);
+        assert_eq!(v["scene"][0]["type"], "text");
+        assert_eq!(v["scene"][0]["label"], "Net Price");
+        // Optional fields absent when None.
+        assert!(v["scene"][0].get("text").is_none());
+        // Round-trips.
+        let back: Clarification = serde_json::from_value(v).expect("deserializes");
+        assert_eq!(back, c);
+    }
+}

{flowproof-0.2.0 → flowproof-0.2.1}/crates/flowproof-agent/src/lib.rs

@@ -5,12 +5,14 @@
 //! scene graph. The replayer never touches this crate.
 
 pub mod author;
+pub mod clarify;
 pub mod heal;
 pub mod llm;
 pub mod recorder;
 pub mod rules;
 pub mod spec;
 
+pub use clarify::{Clarification, ClarifyStage};
 pub use heal::{heal, heal_with_author, HealError, HealReport};
 pub use llm::{HttpModelClient, ModelClient};
 pub use recorder::{record, record_with_author, Author, RecordError, RecordSummary};

{flowproof-0.2.0 → flowproof-0.2.1}/crates/flowproof-agent/src/recorder.rs

@@ -76,6 +76,12 @@ pub enum RecordError {
     NoAuthor { step: String, rules_error: String },
     #[error("driver cannot describe its scene; LLM authoring is unavailable for app '{0}'")]
     NoScene(String),
+    #[error(
+        "cannot author step '{}' ({}): {} — a structured clarification payload with the \
+         live-screen inventory is available via `record --json` or the MCP record tool",
+        .0.step, .0.stage, .0.reason
+    )]
+    NeedsClarification(Box<crate::clarify::Clarification>),
 }
 
 /// Outcome of a recording session.
@@ -372,6 +378,8 @@ fn step_for(id: usize, intent: &str, app: &str, action: &ResolvedAction) -> Step
         ResolvedAction::AssertApi {
             method,
             url,
+            headers,
+            body,
             status,
             body_contains,
             timeout_ms,
@@ -384,10 +392,13 @@ fn step_for(id: usize, intent: &str, app: &str, action: &ResolvedAction) -> Step
             (
                 Vec::new(),
                 Action::Assert(Assertion::Api {
+                    // Raw clones: body string leaves and header values keep
+                    // their ${VAR} refs — tokens never enter the trace.
                     request: flowproof_trace::format::ApiRequest {
                         method: method.clone(),
                         url: url.clone(),
-                        body: None,
+                        body: body.clone(),
+                        headers: headers.clone(),
                     },
                     status: *status,
                     expect: Some(serde_json::Value::Object(expect)),
@@ -601,11 +612,38 @@ fn author_actions<D: AppDriver, C: ModelClient>(
             if author == Author::Rules {
                 return Err(RecordError::Rules(rules_error));
             }
-            let Some(client) = client.as_mut() else {
-                return Err(RecordError::NoAuthor {
+            // Ambiguity from here on ends in a structured clarification:
+            // the driving agent — not flowproof — resolves it and re-records.
+            // `prior` holds the intents already performed, so its length is
+            // this step's index and the live scene reflects their effects.
+            let clarify = |stage, reason: String, rules_err: Option<String>, scene: Vec<_>| {
+                RecordError::NeedsClarification(Box::new(crate::clarify::Clarification {
                     step: intent.to_string(),
-                    rules_error: rules_error.to_string(),
-                });
+                    step_index: prior.len(),
+                    stage,
+                    reason,
+                    rules_error: rules_err,
+                    completed_steps: prior.to_vec(),
+                    scene,
+                    hint: crate::clarify::Clarification::HINT.into(),
+                }))
+            };
+            let Some(client) = client.as_mut() else {
+                let inventory = driver
+                    .scene()
+                    .ok()
+                    .flatten()
+                    .map(|s| crate::clarify::scene_inventory(&s))
+                    .unwrap_or_default();
+                return Err(clarify(
+                    crate::clarify::ClarifyStage::NoModel,
+                    format!(
+                        "no model backend is configured (set FLOWPROOF_AI_PROVIDER / \
+                         FLOWPROOF_AI_API_KEY to enable LLM authoring): {rules_error}"
+                    ),
+                    Some(rules_error.to_string()),
+                    inventory,
+                ));
             };
             let scene = driver
                 .scene()?
@@ -618,9 +656,21 @@ fn author_actions<D: AppDriver, C: ModelClient>(
                 intent,
                 scene: &scene,
             };
-            let action = author_step(*client, &ctx)?;
-            *llm_used = true;
-            Ok(vec![action])
+            match author_step(*client, &ctx) {
+                Ok(action) => {
+                    *llm_used = true;
+                    Ok(vec![action])
+                }
+                // Grounding failure after the retry = genuine ambiguity.
+                // Config errors (bad key, network) stay plain errors.
+                Err(crate::AgentError::Authoring { reason, .. }) => Err(clarify(
+                    crate::clarify::ClarifyStage::Model,
+                    reason,
+                    Some(rules_error.to_string()),
+                    crate::clarify::scene_inventory(&scene),
+                )),
+                Err(other) => Err(other.into()),
+            }
         }
     }
 }
@@ -734,16 +784,33 @@ pub fn record_with_client<D: AppDriver, C: ModelClient>(
                 ResolvedAction::AssertApi {
                     method,
                     url,
+                    headers,
+                    body,
                     status,
                     body_contains,
                     timeout_ms,
                 } => {
+                    // Resolved like `equals` above: the trace keeps the raw
+                    // ${VAR}; only the live probe sees values — including
+                    // header tokens and body string leaves.
                     let probe = flowproof_driver::oob::OobProbe::Api {
                         method: method.clone(),
                         url: flowproof_trace::secret::resolve_refs(url)?,
-                        body: None,
+                        body: match body {
+                            Some(b) => Some(flowproof_trace::secret::resolve_refs_in_json(b)?),
+                            None => None,
+                        },
+                        headers: headers
+                            .iter()
+                            .map(|(k, v)| {
+                                Ok((k.clone(), flowproof_trace::secret::resolve_refs(v)?))
+                            })
+                            .collect::<Result<_, flowproof_trace::secret::MissingSecret>>()?,
                         status: *status,
-                        body_contains: body_contains.clone(),
+                        body_contains: match body_contains {
+                            Some(needle) => Some(flowproof_trace::secret::resolve_refs(needle)?),
+                            None => None,
+                        },
                     };
                     poll_oob(&probe, *timeout_ms, &spec_step.intent())?
                 }
@@ -1212,6 +1279,80 @@ steps:
         assert_eq!(client.calls, 0);
     }
 
+    #[test]
+    fn no_model_backend_yields_clarification_with_scene() {
+        let spec = FlowSpec::parse(
+            "name: Vague
+app: web
+url: https://e.test/x
+steps:
+  - Type acme into the \"Supplier\" field
+  - make required field changes
+",
+        )
+        .expect("parses");
+        let mut driver = MockAppDriver::new(&["Supplier"]);
+        driver.scene = Some(
+            r##"[{"target":"css:#price","tag":"input","type":"text","label":"Net Price"}]"##.into(),
+        );
+        let out = std::env::temp_dir().join("flowproof-clarify-nomodel.trace.jsonl");
+        let err = record_with_client(
+            &spec,
+            &mut driver,
+            &out,
+            Author::Auto,
+            Option::<&mut CountingClient>::None,
+        )
+        .expect_err("vague step with no model must need clarification");
+        let RecordError::NeedsClarification(c) = err else {
+            panic!("expected NeedsClarification, got: {err}");
+        };
+        assert_eq!(c.step, "make required field changes");
+        assert_eq!(c.step_index, 1);
+        assert_eq!(c.stage, crate::ClarifyStage::NoModel);
+        assert_eq!(
+            c.completed_steps,
+            vec!["Type acme into the \"Supplier\" field"]
+        );
+        // The live inventory reached the payload — the driving agent can
+        // see the "Net Price" field exists and rewrite the step.
+        assert_eq!(c.scene.len(), 1);
+        assert_eq!(c.scene[0].label.as_deref(), Some("Net Price"));
+        assert!(c.rules_error.is_some());
+        std::fs::remove_file(&out).ok();
+    }
+
+    #[test]
+    fn ungrounded_model_yields_clarification() {
+        let spec = FlowSpec::parse(
+            "name: Vague
+app: web
+url: https://e.test/x
+steps:
+  - make required field changes
+",
+        )
+        .expect("parses");
+        let mut driver = MockAppDriver::new(&["#price"]);
+        driver.scene = Some(r##"[{"target":"css:#price","tag":"input"}]"##.into());
+        // The model invents a selector on both attempts — grounding fails.
+        let mut client = CountingClient {
+            reply: r##"{"action":"click","target":"css:#invented"}"##.into(),
+            calls: 0,
+        };
+        let out = std::env::temp_dir().join("flowproof-clarify-model.trace.jsonl");
+        let err = record_with_client(&spec, &mut driver, &out, Author::Auto, Some(&mut client))
+            .expect_err("ungroundable step must need clarification");
+        let RecordError::NeedsClarification(c) = err else {
+            panic!("expected NeedsClarification, got: {err}");
+        };
+        assert_eq!(c.stage, crate::ClarifyStage::Model);
+        assert_eq!(client.calls, 2, "one attempt + one self-correcting retry");
+        assert!(c.rules_error.is_some(), "rules diagnostic travels along");
+        assert_eq!(c.scene[0].target, "css:#price");
+        std::fs::remove_file(&out).ok();
+    }
+
     #[test]
     fn unknown_app_is_rejected() {
         let spec =